CPU limits and reservations in Docker - Deep Dive

Overview - CPU limits and reservations

What is it?

CPU limits and reservations in Docker control how much processing power a container can use. Reservations guarantee a minimum CPU share for a container, while limits set the maximum CPU it can consume. This helps manage resources when multiple containers run on the same machine. It ensures fair sharing and prevents one container from slowing down others.

Why it matters

Without CPU limits and reservations, one container could use all the CPU, making others slow or unresponsive. This can cause downtime or poor performance in applications. By controlling CPU usage, Docker helps keep systems stable and predictable, especially in shared environments or production servers.

Where it fits

Before learning CPU limits and reservations, you should understand basic Docker container concepts and resource management. After this, you can explore memory limits, Docker Compose resource settings, and Kubernetes resource quotas for container orchestration.

Mental Model

Core Idea

CPU limits and reservations let you reserve guaranteed CPU power and cap maximum CPU usage for Docker containers to balance performance and fairness.

Think of it like...

Imagine a shared kitchen where each cook has a reserved stove burner to guarantee they can cook, but no one can use more burners than allowed to keep the kitchen running smoothly.

┌─────────────────────────────┐
│        Docker Host CPU       │
│                             │
│  ┌───────────────┐          │
│  │ Container A   │<--Reserved CPU (guaranteed minimum)
│  │  CPU Limit ↑  │<--Max CPU allowed
│  └───────────────┘          │
│  ┌───────────────┐          │
│  │ Container B   │          │
│  │  CPU Limit ↑  │          │
│  └───────────────┘          │
│                             │
└─────────────────────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding Docker CPU Basics

Concept: Learn what CPU resources mean for Docker containers and how Docker shares CPU by default.

Docker containers share the host machine's CPU by default without strict limits. This means containers can use as much CPU as available, competing with each other. CPU is measured in units called CPU shares, which Docker uses to prioritize CPU time when there is contention.

Result

Containers run using available CPU but may compete and slow each other down if many run simultaneously.

Understanding that Docker containers share CPU by default helps explain why controlling CPU usage is important for predictable performance.

2

Foundation

What Are CPU Reservations and Limits?

Concept: Introduce the difference between CPU reservations (guarantees) and CPU limits (caps).

CPU reservation sets a guaranteed minimum CPU share for a container, ensuring it always gets some CPU even under load. CPU limit sets the maximum CPU a container can use, preventing it from using too much and affecting others.

Result

You can guarantee a container gets enough CPU to work well and prevent it from hogging CPU.

Knowing the difference between reservation and limit is key to balancing resource guarantees and fairness.

3

Intermediate

Setting CPU Reservations in Docker

Concept: Learn how to reserve CPU for a container using Docker run options.

Use the option --cpu-reservation to specify the minimum CPU a container should get. For example, docker run --cpu-reservation=0.5 runs a container reserving half a CPU core. This means Docker tries to ensure the container always has access to 50% of one CPU core.

Result

The container will have guaranteed CPU availability even if other containers compete for CPU.

Understanding how to reserve CPU helps prevent performance drops when the host is busy.

4

Intermediate

Applying CPU Limits to Containers

Concept: Learn how to limit the maximum CPU a container can use.

Use the option --cpus to limit CPU usage. For example, docker run --cpus=1.5 limits the container to 1.5 CPU cores max. This prevents the container from using more CPU than allowed, protecting other containers from being starved.

Result

The container cannot exceed the specified CPU usage, ensuring fair CPU sharing.

Knowing how to limit CPU usage prevents resource hogging and keeps systems stable.

5

Intermediate

Combining CPU Reservations and Limits

🤔Before reading on: do you think setting a CPU limit lower than the reservation makes sense? Commit to yes or no.

Concept: Understand how reservations and limits work together and their constraints.

You can set both CPU reservation and limit for a container. The reservation must be less than or equal to the limit. For example, --cpu-reservation=0.5 and --cpus=1.0 means the container is guaranteed 0.5 CPU but can use up to 1 CPU if available.

Result

The container has a guaranteed minimum CPU and a capped maximum CPU, balancing performance and fairness.

Knowing the relationship between reservation and limit helps avoid configuration errors and ensures predictable container behavior.

6

Advanced

How Docker Enforces CPU Limits Internally

🤔Before reading on: do you think Docker limits CPU by stopping processes or by scheduling? Commit to your answer.

Concept: Explore how Docker uses Linux kernel features to enforce CPU limits and reservations.

Docker uses Linux control groups (cgroups) to manage CPU resources. Cgroups control CPU shares and quotas by scheduling CPU time slices for containers. Reservations translate to minimum shares, and limits translate to quotas that restrict CPU time. Docker configures cgroups automatically based on your options.

Result

CPU usage is controlled precisely by the kernel scheduler, ensuring containers get their reserved CPU and do not exceed limits.

Understanding the kernel-level enforcement explains why CPU limits are effective and how they impact container performance.

7

Expert

Surprising Effects of CPU Limits on Container Performance

🤔Before reading on: do you think setting a CPU limit always improves system stability? Commit to yes or no.

Concept: Discover unexpected behaviors and trade-offs when using CPU limits in production.

Setting CPU limits can cause containers to slow down if the limit is too low, leading to increased latency. Also, CPU limits can affect how Docker schedules processes, sometimes causing CPU throttling bursts. In some cases, containers with limits may perform worse than those without, especially if the workload is bursty or multi-threaded.

Result

CPU limits must be chosen carefully; too strict limits can degrade performance instead of improving it.

Knowing these trade-offs helps experts tune CPU settings for real workloads and avoid common pitfalls.

Under the Hood

Docker uses Linux cgroups to control CPU resources. Cgroups assign CPU shares and quotas to container processes. CPU reservation sets a minimum share of CPU time, ensuring the container gets scheduled regularly. CPU limits set a quota that caps the total CPU time a container can consume in a period. The Linux kernel scheduler enforces these rules by allocating CPU time slices accordingly.

Why designed this way?

Linux cgroups provide a flexible, kernel-level way to manage resources without modifying container code. Docker leverages this existing mechanism for efficiency and reliability. This design avoids reinventing scheduling and ensures compatibility with Linux systems. Alternatives like user-space throttling were less precise and more resource-intensive.

┌─────────────────────────────┐
│       Linux Kernel          │
│  ┌───────────────┐          │
│  │ Cgroups CPU   │          │
│  │ Controller    │          │
│  └───────────────┘          │
│       ▲          ▲          │
│       │          │          │
│  CPU Quota   CPU Shares     │
│       │          │          │
│  ┌───────────────┐          │
│  │ Docker Engine │          │
│  │  CPU Limits   │          │
│  │  Reservations │          │
│  └───────────────┘          │
└─────────────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does setting a CPU limit guarantee the container always gets that CPU amount? Commit yes or no.

Common Belief: Setting a CPU limit means the container always gets that CPU amount.

Reality: CPU limits only cap the maximum CPU usage; they do not guarantee the container will get that CPU if the host is busy.

Why it matters: Assuming limits guarantee CPU can lead to performance issues when containers starve for CPU under heavy load.

Quick: If you set CPU reservation higher than the limit, will Docker accept it? Commit yes or no.

Common Belief: You can set CPU reservation higher than the CPU limit without problems.

Reality: Docker requires CPU reservation to be less than or equal to the CPU limit; otherwise, it rejects the configuration.

Why it matters: Misconfiguring these values causes container startup failures or ignored settings.

Quick: Does Docker enforce CPU limits by killing or pausing container processes? Commit yes or no.

Common Belief: Docker enforces CPU limits by stopping or killing container processes when they exceed limits.

Reality: Docker enforces CPU limits by controlling CPU scheduling via cgroups, not by killing or pausing processes.

Why it matters: Misunderstanding enforcement can lead to wrong debugging approaches and misinterpretation of container behavior.

Quick: Does setting CPU limits always improve overall system performance? Commit yes or no.

Common Belief: Applying CPU limits always makes the system more stable and performant.

Reality: CPU limits can sometimes reduce container performance and increase latency if set too low or for bursty workloads.

Why it matters: Blindly applying limits without tuning can degrade application responsiveness and user experience.

Expert Zone

1

CPU reservations do not reserve physical CPU cores but guarantee CPU time slices, which can still be shared among containers.

2

CPU limits interact with container multi-threading; limits apply to total CPU time across all threads, which can cause unexpected throttling.

3

Docker's CPU quota enforcement uses a fixed period (usually 100ms), causing bursty CPU usage patterns that can affect latency-sensitive applications.

When NOT to use

Avoid CPU limits for containers running latency-sensitive or real-time workloads where throttling causes unacceptable delays. Instead, use dedicated CPU pinning or real-time kernel features. Also, in single-container hosts, CPU limits may be unnecessary and add overhead.

Production Patterns

In production, CPU reservations are used to guarantee minimum resources for critical services, while limits protect the host from runaway containers. Combined with monitoring, these settings help maintain service level agreements and prevent noisy neighbor problems.

Connections

Linux Control Groups (cgroups)

CPU limits and reservations in Docker are implemented using Linux cgroups.

Understanding cgroups helps grasp how Docker enforces resource constraints at the kernel level.

Kubernetes Resource Quotas

Kubernetes builds on Docker's CPU limits and reservations to manage container resources in clusters.

Knowing Docker CPU controls prepares you to understand Kubernetes resource management and scheduling.

Traffic Shaping in Networking

Both CPU limits and traffic shaping control resource usage to prevent overload and ensure fairness.

Recognizing this pattern across domains helps design balanced systems that share limited resources effectively.

Common Pitfalls

#1 Setting CPU reservation higher than CPU limit causes errors.

Wrong approach:

docker run --cpu-reservation=2 --cpus=1 mycontainer

Correct approach:

docker run --cpu-reservation=1 --cpus=2 mycontainer

Root cause:

Misunderstanding that reservation must be less than or equal to the limit.

#2 Assuming CPU limit guarantees CPU availability.

Wrong approach:

docker run --cpus=2 mycontainer (expecting container always gets 2 CPUs)

Correct approach:

docker run --cpu-reservation=2 --cpus=2 mycontainer (guarantees minimum and caps max)

Root cause:

Confusing CPU limit (max cap) with CPU reservation (guarantee).

#3 Not setting any CPU limits on a busy host causes resource contention.

Wrong approach:

docker run mycontainer (no CPU limits or reservations)

Correct approach:

docker run --cpu-reservation=0.5 --cpus=1 mycontainer

Root cause:

Ignoring resource management leads to unpredictable container performance.

Key Takeaways

CPU limits cap the maximum CPU a Docker container can use, preventing resource hogging.

CPU reservations guarantee a minimum CPU share, ensuring containers get enough processing power.

Docker uses Linux cgroups to enforce CPU limits and reservations at the kernel scheduler level.

Setting CPU limits too low can degrade container performance and increase latency.

Properly balancing CPU limits and reservations is essential for stable, fair, and predictable containerized applications.

Practice

1. What does setting a CPU limit for a Docker container do?

easy

A. It pauses the container when CPU usage is high.

B. It restricts the maximum CPU the container can use.

C. It sets the container to use all available CPUs.

D. It guarantees the container will always get that CPU amount.

Solution

1. Step 1: Understand CPU limit meaning

   A CPU limit restricts the maximum CPU a container can use, preventing it from using more than set.

2. Step 2: Differentiate from CPU reservation

   CPU reservation guarantees minimum CPU, not a maximum limit.

3. Final Answer:

   It restricts the maximum CPU the container can use. -> Option B

4. Quick Check:

   CPU limit = max CPU allowed [OK]

Hint: Limit means max CPU allowed, reservation means minimum guaranteed [OK]

Common Mistakes:

• Confusing CPU limit with CPU reservation
• Thinking CPU limit guarantees CPU
• Assuming CPU limit pauses container

2. Which of the following is the correct Docker run command to limit a container to use at most 0.5 CPUs?

easy

A. docker run --cpus=0.5 myimage

B. docker run --cpu-limit=0.5 myimage

C. docker run --cpu-reservation=0.5 myimage

D. docker run --cpu=0.5 myimage

Solution

1. Step 1: Identify correct flag for CPU limit

   The correct Docker flag to limit CPU usage is --cpus, which accepts a decimal value.

2. Step 2: Check other options for correctness

   --cpu-limit and --cpu-reservation are invalid flags; --cpu is not a valid flag either.

3. Final Answer:

   docker run --cpus=0.5 myimage -> Option A

4. Quick Check:

   Use --cpus to set CPU limit [OK]

Hint: Use --cpus flag to limit CPU usage in docker run [OK]

Common Mistakes:

• Using non-existent flags like --cpu-limit
• Confusing CPU limit with CPU reservation flags
• Using --cpu instead of --cpus

3. Given the command docker service create --cpus=1.5 --reserve-cpu=1 myimage, what does this configuration mean?

medium

A. The container can use up to 1.5 CPUs and is guaranteed 1 CPU.

B. The container is limited to 1 CPU and has no guaranteed CPU.

C. The container can use up to 1 CPU and is guaranteed 1.5 CPUs.

D. The container is guaranteed 1.5 CPUs and limited to 1 CPU.

Solution

1. Step 1: Interpret --cpus flag

   --cpus=1.5 means the container can use up to 1.5 CPUs maximum.

2. Step 2: Interpret --reserve-cpu flag

   --reserve-cpu=1 means the container is guaranteed at least 1 CPU.

3. Final Answer:

   The container can use up to 1.5 CPUs and is guaranteed 1 CPU. -> Option A

4. Quick Check:

   --cpus = max CPU, --reserve-cpu = guaranteed CPU [OK]

Hint: Max CPU = --cpus, guaranteed CPU = --reserve-cpu [OK]

Common Mistakes:

• Swapping meanings of limit and reservation
• Assuming reservation is max CPU
• Ignoring one of the flags

4. You run docker service create --reserve-cpu=2 myimage on a host with only 1 CPU. What is the likely outcome?

medium

A. Docker will reserve 2 CPUs regardless of host capacity.

B. Docker will throw an error and refuse to start the container.

C. Docker will reserve CPU as best as possible but cannot guarantee 2 CPUs.

D. Docker will limit the container to 1 CPU automatically.

Solution

1. Step 1: Understand CPU reservation vs host capacity

   CPU reservation requests minimum CPU but Docker cannot guarantee more CPUs than host has.

2. Step 2: Behavior when reservation exceeds host CPUs

   Docker tries to reserve as much as possible but cannot guarantee more than available CPUs; it does not error out.

3. Final Answer:

   Docker will reserve CPU as best as possible but cannot guarantee 2 CPUs. -> Option C

4. Quick Check:

   Reservation tries best effort, no error if host CPU insufficient [OK]

Hint: Reservation can't exceed host CPU, but no error thrown [OK]

Common Mistakes:

• Expecting error when reservation > host CPU
• Thinking Docker limits container automatically
• Confusing reservation with limit

5. You want to run two containers on a 4-CPU host. Container A needs at least 1 CPU but can use up to 2 CPUs. Container B needs at least 1.5 CPUs but can use up to 2.5 CPUs. Which of the following flag sets correctly set CPU limits and reservations to meet these requirements without overcommitting the host?

hard

A. Container A: --reserve-cpu=1.5 --cpus=2, Container B: --reserve-cpu=1 --cpus=2.5

B. Container A: --reserve-cpu=2 --cpus=1, Container B: --reserve-cpu=2.5 --cpus=1.5

C. Container A: --reserve-cpu=1 --cpus=1.5, Container B: --reserve-cpu=1.5 --cpus=2

D. Container A: --reserve-cpu=1 --cpus=2, Container B: --reserve-cpu=1.5 --cpus=2.5

Solution

1. Step 1: Check CPU reservations sum

   Container A reserves 1 CPU, Container B reserves 1.5 CPUs; total 2.5 CPUs < 4 CPUs host, so no overcommit.

2. Step 2: Check CPU limits sum

   Container A max 2 CPUs, Container B max 2.5 CPUs; total 4.5 CPUs > 4 CPUs host, but limits can exceed host CPUs as they are max caps, not guaranteed.

3. Step 3: Verify options

   Container A: --reserve-cpu=1 --cpus=2, Container B: --reserve-cpu=1.5 --cpus=2.5 matches requirements exactly. Others swap reservation and limit or exceed reservation beyond requirements.

4. Final Answer:

   Container A: --reserve-cpu=1 --cpus=2, Container B: --reserve-cpu=1.5 --cpus=2.5 -> Option D

5. Quick Check:

   Reservations sum < host CPUs, limits set max usage [OK]

Hint: Sum reservations ≤ host CPUs; limits can be higher [OK]

Common Mistakes:

• Swapping reservation and limit values
• Overcommitting CPU reservations beyond host capacity
• Confusing reservation with limit in commands