Skip to content

Docker audit fix · Runtime & Resources

How to Limit CPU Usage in Docker Containers

A Docker container is unlimited on CPU when both NanoCpus and CpuQuota are 0, which lets a runaway loop or a cryptominer take every core the host has. Set --cpus for a real ceiling; --cpu-shares only sets relative priority.

Hiren KalariyaHiren KalariyaLast reviewed cpu-limits
CtrlOpsCPU LimitsLOW

What did your audit say?

WARN · when the audit printed

Some have none

The named containers have neither flag set and can use every core on the host whenever their workload asks for it.

Severity
Low
Needs root or sudo
Yes
Results it can return
WARN · SKIP · PASS
Check in this audit
4 of 6

Every threshold on this page is transcribed from the docker-security-runtime-resources audit script that CtrlOps runs, and a build check fails if the two ever disagree. See all 6 Runtime & Resources checks, or how the audit runs.

The check inspects every running container with the template {{if and (eq .HostConfig.NanoCpus 0) (eq .HostConfig.CpuQuota 0)}}{{.Name}} {{end}}, so it reads two fields: .HostConfig.NanoCpus, set by --cpus, and .HostConfig.CpuQuota, set by --cpu-quota. A container counts as unlimited only when both are 0, which means either flag on its own is enough to satisfy the check. An empty list of unlimited containers is the PASS; one or more is the WARN, which reports the count against the number of running containers and names up to five.

Needs a reachable daemon and at least one running container; otherwise SKIP. A container counts as unlimited only when both .HostConfig.NanoCpus (set by --cpus) and .HostConfig.CpuQuota (set by --cpu-quota) are 0 - either one satisfies the check. --cpu-shares is a relative weight, not a limit, and does not count. --cpuset-cpus, which pins a container to specific cores, is also not considered a limit here. Severity is LOW because this is a fair-sharing and availability control rather than a containment boundary.

What each result means
ResultWhenWhat it means
SKIPNo running containersNothing was verified. No container's CPU settings were read, so this is not a clean bill of health.
PASSEvery container has a CPU limitEvery running container has a non-zero --cpus or --cpu-quota value, so none of them can take the whole machine.
WARNSome have noneThe named containers have neither flag set and can use every core on the host whenever their workload asks for it.

CPU exhaustion (a cryptominer after a compromise, a runaway loop, a ReDoS) starves every co-located service, and from outside the host looks down while technically still running. OWASP Docker Cheat Sheet Rule #7 asks for CPU limits. CIS Docker 5.11 "Ensure that CPU priority is set appropriately on containers" covers the related --cpu-shares weight; this check asks for more than CIS does, a hard ceiling.

  • --cpu-shares (relative weight) and --cpuset-cpus (pinning) are not counted as limits; they do help under contention but do not cap usage.
  • In Compose, deploy.resources.limits.cpus or the service-level cpus sets NanoCpus and satisfies the check; cpu_shares and cpuset do not.
  • Limits are CFS quotas; setting --cpus 0.5 on a single-threaded service can add latency from throttling. Measure with docker stats and /sys/fs/cgroup/.../cpu.stat nr_throttled.
  1. Measure normal CPU use

    docker stats reports CPU as a percentage of one core, so 150% is one and a half cores. Note each container's peak under typical load.

    sh
    docker stats --format 'table {{.Name}}\t{{.CPUPerc}}'

  2. Set a ceiling with --cpus

    Set it above the measured peak. A typical web server needs 0.5 to 1.0 CPUs.

    sh
    docker run --cpus 1.5 ...

    In Compose:

    yaml
    services:  app:    deploy:      resources:        limits:          cpus: "1.5"

  3. Apply it

    Recreate the container, or change a running one in place with docker update. Keep the Compose file in step, or the next recreate removes the limit.

    sh
    docker compose up -d --force-recreate# or, in place:docker update --cpus 1.5 <name>

  4. Check for throttling

    sh
    docker exec <name> cat /sys/fs/cgroup/cpu.stat

    A nr_throttled value that climbs quickly under normal load means the ceiling is too tight; raise it.

sh
docker inspect -f '{{.Name}} nanocpus={{.HostConfig.NanoCpus}} quota={{.HostConfig.CpuQuota}} shares={{.HostConfig.CpuShares}}' $(docker ps -q)# expected: a non-zero nanocpus or quota for every containerdocker stats --no-stream --format 'table {{.Name}}\t{{.CPUPerc}}'# expected: no container sustained near (cores x 100%)# The cgroup's own view (cgroup v2: "quota period"):docker exec <name> cat /sys/fs/cgroup/cpu.max# expected: e.g. "150000 100000" for --cpus=1.5, not "max 100000"

Debugging

  • This one message covers two different cases: the audit could not reach the Docker daemon, or it reached it and nothing was running. Run docker ps as the audit user, then sudo docker ps. If both fail, the daemon is unreachable: check systemctl status docker, then run the audit as root or give the account sudo. If they work but list nothing, there is genuinely nothing to evaluate, and a stopped container is never checked. The Docker Inventory check reports the two cases separately, so its result tells you which one you hit.
  • Correct behaviour, not a bug. Shares only decide relative priority when the CPU is contended; they place no ceiling on a container. Use --cpus (Compose deploy.resources.limits.cpus or cpus) for a real limit.
  • Current docker compose honours deploy.resources.limits.cpus without Swarm, so the usual causes are that the container was not recreated after the edit, or the value sits under reservations instead of limits. docker compose config shows the file as Compose resolves it; then run docker compose up -d --force-recreate.
  • A batch or build container that should use spare capacity is a legitimate exception. --cpu-shares plus a --cpus ceiling well above normal usage keeps it burstable while still satisfying the check.
  • CFS quota throttling is bursty for latency-sensitive workloads. Check throttling with docker exec <name> cat /sys/fs/cgroup/cpu.stat (look at nr_throttled) and raise the limit. Pinning with --cpuset-cpus avoids quota throttling, but on its own it does not count as a limit for this check, so keep a --cpus ceiling alongside it.

Sources

Next

Re-run the Runtime & Resources audit after applying the fix and confirm this check moves to PASS. CtrlOps runs all 6 checks over your existing SSH connection and scores the result, so the change is visible without reading another config file.

Download for MacDownload for WindowsAll 6 Runtime & Resources fixes

14-day free trial, no credit card required.

Explore article with AI tools

Written by

Hiren Kalariya

Co-Founder & CEO, TST Technology

Hiren Kalariya is the Co-Founder and CEO of TST Technology and the product lead behind CtrlOps, a local-first desktop app that makes Linux server management fast and easy for developers and DevOps teams. Over the past five years he has shipped 60+ production systems, and he still tests every tool he writes about on real servers.

Stop juggling tools. Start managing fleets.

PuTTY
Termius
MobaXterm
WinSCP
SecureCRT
Royal TS
Warp
CtrlOps14 tools left
Webmin
aaPanel
RunCloud
Dokploy
IP spreadsheet
bash (2)
sticky notes

One app. All your servers. No context switching. Free to start, free to leave.

Start instantly · No credit card · Cancel anytime

Your privacy preferences. We use product analytics to improve CtrlOps. Google Analytics cookies and live chat stay off until you allow them. Cookie policy