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.