Docker Resource Management

Docker Resource Management

Why Limit Resources?

By default, a container has no limits - it can use all available CPU and memory on the host. If a container leaks memory or goes into an infinite loop, it can starve other containers or crash the entire system.

Resource limits prevent any one container from consuming too much.

Without limits:
  Container A goes crazy -> uses 100% CPU -> Container B + C starve -> system crashes

With limits:
  Container A limited to 1 CPU -> goes crazy -> only uses its 1 CPU -> B and C unaffected

Memory Limits

Set Memory Limit at Runtime

# Limit to 512 MB
docker run -d --memory 512m nginx

# Limit to 1 GB
docker run -d --memory 1g nginx

# Limit in bytes
docker run -d --memory 536870912 nginx   # 512 MB in bytes

# Set memory + swap limit
# --memory-swap = total memory + swap
# --memory 512m --memory-swap 1g -> 512m RAM + 512m swap
docker run -d --memory 512m --memory-swap 1g nginx

# Set swap = memory (no extra swap)
docker run -d --memory 512m --memory-swap 512m nginx

# Disable swap completely
docker run -d --memory 512m --memory-swap 512m nginx

# Unlimited swap
docker run -d --memory 512m --memory-swap -1 nginx

# Soft limit (memory reservation) - Docker tries not to exceed this
docker run -d --memory 512m --memory-reservation 256m nginx

Memory Limit Units

CPU Limits

--cpus - Limit CPU Usage

# Allow the container to use at most 1.5 CPUs
docker run -d --cpus 1.5 nginx

# Limit to 0.5 of a CPU
docker run -d --cpus 0.5 nginx

# Limit to 2 full CPUs
docker run -d --cpus 2 nginx

--cpu-shares - Relative CPU Weight

Sets the relative weight (priority) for CPU time. Default is 1024.

# Give this container double the CPU priority (2048 vs default 1024)
docker run -d --cpu-shares 2048 nginx

# Lower priority (gets less CPU when there is contention)
docker run -d --cpu-shares 512 nginx

# Default
docker run -d --cpu-shares 1024 nginx

--cpu-shares only matters when CPUs are being contested by multiple containers. If only one container is running, it can use 100% of CPU regardless.

--cpuset-cpus - Pin to Specific CPU Cores

# Run on CPU 0 only
docker run -d --cpuset-cpus 0 nginx

# Run on CPUs 0 and 1
docker run -d --cpuset-cpus "0,1" nginx

# Run on CPUs 0, 1, and 2
docker run -d --cpuset-cpus "0-2" nginx

--cpu-period and --cpu-quota - Fine-Grained CPU Control

# Limit to 50% of one CPU
# period = 100000 microseconds (0.1 seconds)
# quota = 50000 microseconds = 50% of one CPU
docker run -d --cpu-period 100000 --cpu-quota 50000 nginx

Setting Limits at Runtime (Update Running Container)

# Update memory limit of a running container
docker update --memory 1g my-nginx

# Update CPU limit
docker update --cpus 2 my-nginx

# Update both
docker update --memory 512m --cpus 1.5 my-nginx

# Update restart policy
docker update --restart always my-nginx

Resource Limits in Docker Compose

version: "3.9"

services:
  web:
    image: nginx
    deploy:
      resources:
        limits:
          cpus: "0.50"       # Max 0.5 CPU
          memory: 512M       # Max 512 MB RAM
        reservations:
          cpus: "0.25"       # Minimum guaranteed 0.25 CPU
          memory: 256M       # Minimum guaranteed 256 MB RAM

Monitoring Resource Usage

# Live stats for all containers
docker stats

# One-time snapshot
docker stats --no-stream

# Custom format showing CPU and memory
docker stats --no-stream --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.MemPerc}}"

# Stats for a specific container
docker stats my-nginx

# JSON output
docker stats --no-stream --format "{{json .}}"

Example output:

NAME       CPU %   MEM USAGE / LIMIT    MEM %   NET I/O       BLOCK I/O
my-nginx   0.01%   3.5MiB / 512MiB      0.68%   1.2kB / 0B    0B / 0B

What Happens When Limits Are Exceeded

# Check if a container was OOM killed
docker inspect -f '{{.State.OOMKilled}}' my-app
# Output: true (was OOM killed) or false

# Check exit code
docker inspect -f '{{.State.ExitCode}}' my-app
# 137 = OOM kill signal

Resource Management Quick Reference