CPU, Memory, PIDs, Devices, ulimits, cgroups v2, Reservations, and Container Resource Governance: Configuration, Design Choices, and Tradeoffs

1. Start with the question, not the flag

Before selecting a Docker option, state the failure you are trying to prevent or the service objective you are trying to protect. “Use less CPU” is vague. “Prevent this batch job from consuming more than one core while latency-sensitive services share the host” leads naturally to a CPU quota. “Keep a licensed single-thread workload on CPUs 2–3” points toward affinity. “Prefer this service under contention” points toward relative weight.

2. Hard limits versus reservations and soft controls

3. CPU quota versus cpuset

A quota changes how much CPU time is available. A cpuset changes where the process may run. They can be combined, but each narrows a different dimension. Affinity can improve isolation or cache locality in specialized workloads, yet it can also strand capacity and reduce scheduler flexibility. Prefer quota first unless measurements justify topology-aware placement.

Relative CPU weight is meaningful only when workloads contend. A container with low shares can still use idle CPU. This distinction is essential when interpreting a benchmark on an otherwise quiet developer machine.

4. Memory and swap policy: choose a failure mode deliberately

Swap can absorb bursts but adds latency. No swap makes the memory ceiling more deterministic but increases the chance that the cgroup kills a process during spikes. Docker documents that --memory-swap is total memory plus swap; setting it equal to --memory disables additional swap, while -1 allows unlimited swap up to host availability.

For latency-sensitive services, “no swap” may be defensible. For batch work, some swap may be acceptable. The correct policy depends on SLOs, working-set behavior, host storage, and failure recovery—not ideology.

5. Per-container governance versus host/VM governance

Container limits partition available capacity; they do not create capacity. On Docker Desktop, the Linux VM itself has configurable CPU, RAM, swap, and disk limits. A four-CPU container cannot consume four host CPUs if the Docker VM has only two. Similarly, several containers can each have 2 GiB hard limits while the VM has less aggregate RAM, making simultaneous peaks impossible.

Capacity planning therefore has two levels: host/VM envelope and workload envelopes. Keep both in the evidence packet.

6. Device access versus a mediated service

Direct device mapping couples a workload to one daemon host and expands authority. Prefer a mediated service, network API, or runtime-specific device plugin/driver when it provides the function without direct device-node access. If direct mapping is required, pin the exact device and access mode; do not mount all of /dev and do not use privileged mode as a convenience.

7. Compose resource declarations: portable model, platform-specific enforcement

The Compose Deploy Specification models limits and reservations for CPU, memory, PIDs, and devices. That declarative model is valuable, but actual enforcement depends on the platform executing it. Validate the normalized Compose model and then inspect the resulting container HostConfig/cgroups on the target platform.

# Example model; verify support on the target platform before relying on reservations.
services:
  api:
    image: example/api@sha256:RECORD_THE_REAL_DIGEST
    deploy:
      resources:
        limits:
          cpus: "0.50"
          memory: 256M
          pids: 128
        reservations:
          memory: 128M

8. Decision table: choose an approach with prerequisites and evidence

9. Reproducibility and rollback

Record the image digest and resource policy together. If a release changes memory behavior, compare the same workload and policy before deciding the limit is wrong. Rollback can mean restoring the previous image, restoring the previous envelope, or both. Changing limits without preserving the prior configuration destroys the experiment.

Knowledge check

Official references and version notes

• Docker Docs — Resource constraints — CPU and memory hard/soft controls, swap semantics, and OOM guidance.
• Docker Docs — Runtime metrics — docker stats, cgroup discovery, and cgroups v2 behavior.
• Docker CLI — docker container run — CPU, memory, PID, ulimit, device, and cgroup options.
• Docker CLI — docker container stats — CPU, memory, PIDs, I/O, and one-shot JSON/template output.
• Compose Deploy Specification — resources — limits, reservations, PIDs, and device reservations.
• Docker Desktop — Resources — CPU/memory/swap capacity of the Docker Desktop Linux VM.
• Docker Engine 29 release notes — current Engine baseline and recent runtime/ulimit changes.
• Linux kernel — Control Group v2 — controller semantics for cpu.*, memory.*, and pids.*.