Skip to main content

Docker CPU Management

Introduction​

In containerized environments, effective CPU management is crucial for maintaining application performance, ensuring system stability, and maximizing resource utilization. Docker provides several mechanisms to control how containers use CPU resources on host machines.

This guide explains Docker's CPU management features, how to configure them properly, and best practices for optimizing container performance. Whether you're running a single container or orchestrating multiple services, understanding these concepts will help you create more efficient and stable applications.

Understanding Docker CPU Resources​

Before diving into configuration, let's understand how Docker interacts with CPU resources:

  1. CPU Shares - Relative weighting for CPU usage during contention
  2. CPU Quotas - Hard limits on how much CPU time a container can use
  3. CPU Sets - Restrictions on which specific CPU cores a container can access

Docker allows precise control over these resources, enabling you to prioritize critical containers, prevent resource starvation, and implement performance isolation.

Basic CPU Management Options​

CPU Shares​

CPU shares define the relative priority of containers when competing for CPU time. By default, each container gets 1024 shares. This value doesn't limit CPU usage when resources are available, but rather allocates proportional time during contention.

bash
# Run a container with 512 CPU shares (half the default priority)
docker run -d --cpu-shares=512 nginx

# Run a container with 2048 CPU shares (twice the default priority)
docker run -d --cpu-shares=2048 nginx

In this example, if both containers are running CPU-intensive workloads, the second container would receive approximately 4 times more CPU time than the first (2048 vs 512).

CPU Quotas and Periods​

For stricter control, Docker allows setting hard limits using the --cpu-quota and --cpu-period flags:

  • CPU Period: Specifies the scheduling period in microseconds (default: 100000 or 100ms)
  • CPU Quota: Maximum CPU time a container can use during the period
bash
# Limit container to 50% of a single CPU core
docker run -d --cpu-quota=50000 --cpu-period=100000 nginx

# Limit container to 2 CPU cores
docker run -d --cpu-quota=200000 --cpu-period=100000 nginx

The Simplified --cpus Flag​

Docker introduced a more intuitive --cpus flag that specifies the number of CPUs a container can use:

bash
# Limit container to 0.5 CPUs
docker run -d --cpus=0.5 nginx

# Limit container to 1.5 CPUs
docker run -d --cpus=1.5 nginx

This is equivalent to setting --cpu-quota to --cpu-period multiplied by the CPU count.

Advanced CPU Management​

CPU Pinning with --cpuset-cpus​

For workloads requiring deterministic performance or NUMA optimization, you can restrict containers to specific CPU cores:

bash
# Restrict container to CPU cores 0 and 1
docker run -d --cpuset-cpus="0,1" nginx

# Restrict container to CPU cores 0 through 3
docker run -d --cpuset-cpus="0-3" nginx

This approach is particularly useful for:

  • Workloads with specific latency requirements
  • Avoiding CPU cache thrashing
  • Isolating critical services from each other

CPU Allocation in Docker Compose​

For multi-container applications managed with Docker Compose, CPU settings can be specified in the docker-compose.yml file:

yaml
version: '3'
services:
  web:
    image: nginx
    deploy:
      resources:
        limits:
          cpus: '0.5'
    # Alternative syntax for older versions
    # cpus: '0.5'
  
  api:
    image: my-api-service
    deploy:
      resources:
        limits:
          cpus: '1.5'
        reservations:
          cpus: '0.5'

In this example:

  • The web service is limited to 0.5 CPU cores
  • The api service is limited to 1.5 CPU cores, with 0.5 cores reserved

Real-World Example: Multi-Tier Application​

Let's examine how to apply CPU management to a typical three-tier web application:

yaml
version: '3'
services:
  nginx:
    image: nginx:latest
    deploy:
      resources:
        limits:
          cpus: '0.5'
        reservations:
          cpus: '0.25'
    # Other configuration...
  
  app_server:
    image: my-application:latest
    deploy:
      resources:
        limits:
          cpus: '2.0'
        reservations:
          cpus: '1.0'
    # Other configuration...
  
  database:
    image: postgres:latest
    deploy:
      resources:
        limits:
          cpus: '1.0'
        reservations:
          cpus: '0.5'
    cpuset: "0,1"
    # Other configuration...

This configuration:

  1. Gives the app server the most CPU resources (2 cores) since it handles business logic
  2. Allocates 1 CPU to the database with pinning to specific cores for consistent performance
  3. Assigns minimal resources to the NGINX proxy since it's primarily I/O bound

Monitoring CPU Usage​

To effectively manage CPU resources, you need visibility into actual usage. Docker provides several ways to monitor container CPU consumption:

Using docker stats​

The simplest way to view real-time CPU usage:

bash
docker stats

Sample output:

CONTAINER ID   NAME         CPU %     MEM USAGE / LIMIT     MEM %     NET I/O           BLOCK I/O         PIDS
7c5a2d4c6e09   web          5.10%     21.14MiB / 1.952GiB   1.06%     648B / 648B       0B / 0B           2
9a0b9f9c8d7e   api          35.92%    42.16MiB / 1.952GiB   2.11%     1.44kB / 1.44kB   0B / 0B           23

Using docker inspect​

To view the CPU configuration of a running container:

bash
docker inspect --format='{{.HostConfig.CpuShares}}' my_container
docker inspect --format='{{.HostConfig.NanoCpus}}' my_container

Collecting Historical Data​

For longer-term monitoring, consider tools like:

  • Prometheus with Docker metrics exporter
  • cAdvisor for container resource usage
  • Docker's built-in metrics API

Best Practices for Docker CPU Management​

  1. Start with monitoring before setting limits

    • Observe natural resource usage patterns before applying constraints

  2. Use relative shares for non-critical applications

    • --cpu-shares provides flexible prioritization without hard caps

  3. Apply hard limits for predictable multi-tenant environments

    • --cpus or --cpu-quota prevents noisy neighbors

  4. Reserve CPU for critical services

    • Ensure important containers always have necessary resources

  5. Consider CPU affinity for latency-sensitive workloads

    • --cpuset-cpus can improve cache locality and reduce scheduling jitter

  6. Test performance under load

    • Simulate production conditions to validate your CPU constraints

  7. Be cautious with CPU pinning in dynamic environments

    • Fixed CPU assignments can limit scheduler flexibility

  8. Document your reasoning

    • Record why specific limits were chosen for future reference

Troubleshooting CPU Issues​

Symptoms of CPU Constraints​

  • Throttling messages in logs: Look for cgroup CPU throttling events
  • Increased response latency: Services taking longer to process requests
  • Degraded throughput: Fewer requests handled per second

Common Problems and Solutions​

  1. Container being throttled unexpectedly

    bash
    # Check if container is hitting CPU limits
    docker stats --no-stream my_container

    # Increase CPU quota if needed
    docker update --cpus=2 my_container

  2. Uneven performance across containers

    bash
    # Verify CPU shares for priority containers
    docker inspect --format='{{.HostConfig.CpuShares}}' container1
    docker inspect --format='{{.HostConfig.CpuShares}}' container2

    # Adjust shares to prioritize important services
    docker update --cpu-shares=2048 important_container

  3. CPU usage spikes affecting all containers

    bash
    # Identify which container is causing the issue
    docker stats

    # Apply appropriate limits
    docker update --cpus=1 problematic_container

Summary​

Docker's CPU management features provide fine-grained control over how containers utilize processor resources. By understanding and properly configuring CPU shares, quotas, and CPU sets, you can:

  • Ensure critical services get the resources they need
  • Prevent individual containers from negatively impacting others
  • Optimize overall system performance and stability
  • Create more predictable application behavior

While the default Docker settings work well for many applications, proper CPU management becomes essential as you scale your containerized infrastructure.

Additional Resources​

Exercises​

  1. Compare the performance of a CPU-intensive application with different --cpu-shares values
  2. Set up a multi-container application with appropriate CPU limits and monitor performance
  3. Experiment with CPU pinning to measure the impact on a database container's performance
  4. Create a Docker Compose file that properly allocates CPU resources based on each service's needs
  5. Write a script to monitor container CPU usage and dynamically adjust limits based on demand

If you spot any mistakes on this website, please let me know at [email protected]. I’d greatly appreciate your feedback! :)