2.3.2.1 Cgroup CPU Limits

Cgroup CPU limits constrain how much processor time a container's processes are allowed to consume, using two complementary mechanisms: relative CPU shares, which determine priority when CPU is contended, and absolute CPU quotas, which cap usage even when the CPU would otherwise be idle.

Relative CPU Shares

CPU shares define a proportional weighting between containers competing for the same CPU resources; a container with twice the shares of another gets roughly twice the CPU time when both are actively competing for it, but neither is capped if the CPU has spare capacity.

docker run -d --cpu-shares=1024 --name high-priority myapp:1.0
docker run -d --cpu-shares=512 --name low-priority myapp:2.0

Under contention, high-priority receives roughly twice the CPU time low-priority does, but if low-priority is the only container actively using the CPU, it can still use as much as is available.

Absolute CPU Quotas

A hard CPU limit, by contrast, caps usage at a fixed amount regardless of whether the CPU is otherwise idle, which is useful when predictable, capped resource consumption matters more than maximizing utilization.

docker run -d --cpus=0.5 myapp:1.0

This container can never use more than half of one CPU core's worth of processing time, even if the rest of the host's CPU capacity is completely unused at that moment.

Combining Shares and Quotas

Both mechanisms can be used together: a quota establishes an absolute ceiling, while shares determine how containers without quotas, or operating below their quota, divide contended CPU time among themselves.

docker run -d --cpus=2 --cpu-shares=1024 myapp:1.0

Observing CPU Limit Enforcement

The effect of a CPU limit can be observed directly by running a CPU-intensive workload inside a constrained container and comparing its actual usage against the configured limit.

docker run --cpus=0.5 --rm alpine sh -c "yes > /dev/null"
docker stats --no-stream

The reported CPU usage percentage for this container should plateau near the configured limit, rather than consuming an entire core, despite the workload being designed to use as much CPU as possible.

Why CPU Limits Matter

Configuring CPU limits appropriately balances two competing goals: giving each container a fair, predictable amount of processing capacity, and making efficient use of a host's total available CPU rather than leaving capacity unused due to overly conservative limits.