Q: A container is consuming 100% CPU. How do you limit it without restarting?
To limit container CPU without restarting it, run docker update --cpus 0.5 [container]. The daemon rewrites the container's cgroup CPU quota live, so the process keeps running with the same PID and state.
Want to master this scenario in a live sandbox? KodeKloud's Docker Certified Associate (DCA) Hands-On Lab Course covers this exact problem with hands-on terminal drills.
🛠️ Production Runbook & Step-by-Step Resolution
Direct Answer: To <strong>limit container CPU without restarting</strong> it, run <code>docker update --cpus 0.5 <container></code>. The daemon rewrites the container's cgroup CPU quota live, so the process keeps running with the same PID and state. Interviewers ask this because it separates people who know that resource limits are cgroup settings (adjustable at runtime) from those who only know <code>docker run</code> flags. A strong answer also covers containing the blast radius first, finding why the CPU is pegged, and making the limit permanent in Compose or your orchestrator so it survives the next redeploy.
Mental model: CPU limits are live cgroup settings
Docker translates CPU flags into cgroup files on the host, and the kernel scheduler enforces them, which is why they can change while the process runs.
- Hard cap:
--cpussets a CFS quota (cgroup v2cpu.max). The container is throttled once it uses its quota in a scheduling period. - Relative weight:
--cpu-sharesonly matters under contention. It does not cap anything on an idle host, so it will not stop a container from using 100% of a free CPU. - Pinning:
--cpuset-cpusrestricts which cores the container may run on, useful for noisy-neighbour isolation. - Why no restart: these values live in the cgroup, not inside the image or process, so the daemon can rewrite them at runtime.
- Cgroup versions: modern distributions default to cgroup v2 where the quota is
cpu.max, while older hosts use v1 files such ascpu.cfs_quota_us. The Docker command is identical, but the paths you inspect differ.
Hands-on: limit container CPU without restarting
Identify the offender, apply the cap, and check that it took effect.
docker stats --no-stream --format 'table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}'
# NAME CPU % MEM USAGE / LIMIT
# my-app 398.12% 612MiB / 15.6GiB
docker update --cpus 1.5 my-app # prints: my-app
docker update --cpu-shares 512 my-app # lower weight under contention
# Pin to cores 0 and 1 only
docker update --cpuset-cpus 0,1 my-app
- Find it:
docker stats --no-streamshows CPU% per container. Note that 100% means one full core, so a busy multi-threaded process can show several hundred percent. - Apply the cap:
docker update --cpus 1.5 my-apptakes effect immediately for the running container. - Combine with memory carefully: if you lower
--memoryin the same call, also pass--memory-swap, otherwise the update can be rejected. - Restart policy:
docker update --restart unless-stopped my-appuses the same mechanism if you also want crash recovery. - Safe first response: in an incident, cap the container first to protect neighbouring workloads on the same host, then investigate. A limit that is slightly too low is cheaper than a node where every service is starved.
Verify the limit is actually enforced
Never trust the command output alone. Confirm the setting and watch throttling.
- Inspect the config:
docker inspect --format '{{.HostConfig.NanoCpus}}' my-appshould show1500000000for 1.5 CPUs. - Watch live usage:
docker stats my-appshould settle near 150% instead of the earlier spike. - Read the cgroup (v2): on the host,
cat /sys/fs/cgroup/system.slice/docker-<full-id>.scope/cpu.maxshows quota and period. With the cgroupfs driver the path differs, so checkdocker infofor the cgroup driver and version. - Check throttling:
cpu.statin the same directory reportsnr_throttledandthrottled_usec. Rising values prove the cap is biting. - What to capture: before changing anything, save
docker logs,docker topand a quickdocker statssample so the evidence exists for the post-incident review even if the problem disappears after throttling.
Failure modes: a cap treats the symptom, not the cause
Limiting CPU buys time. You still need to learn why the process is spinning.
- Inspect processes:
docker top my-appmaps container processes to host PIDs, which you can profile withtop -H -p <pid>orperf top -p <pid>. - Typical causes: an infinite retry loop, a runaway regex or GC thrash, a traffic spike, or a crypto-miner in a compromised image. Check
docker logs --since 10m my-appand the image provenance. - Throttling hurts latency: a too-tight quota makes request-serving apps stall in bursts even though average CPU looks fine. Raise the cap if p99 latency worsens.
- Kubernetes caveat: pod CPU limits are not resizable in place on 1.28-1.31 without enabling an alpha feature gate, so the equivalent there is editing the Deployment and letting it roll.
- Decide whether to scale: if the load is legitimate traffic rather than a bug, a cap only moves the pain to users. Add replicas behind the load balancer or raise capacity instead of throttling real demand.
Production practice: make the limit permanent
docker update changes are lost when the container is recreated from its original definition.
services:
my-app:
image: registry.example.com/my-app:1.4.2
deploy:
resources:
limits:
cpus: "1.5"
memory: 1G
- Compose: set
deploy.resources.limits.cpus(or service-levelcpus) and rundocker compose up -dto recreate with the new value. - Alert before it pages: export cAdvisor or Docker metrics to Prometheus and alert on sustained CPU near the limit plus throttling ratio.
- Defaults: make limits mandatory in templates so no container ships without a cap.
- Review cadence: revisit limits after each release, because a new code path can change the CPU profile, and stale limits are a common source of mysterious latency regressions.
- A container at 100% CPU: I contain it with <code>docker update --cpus</code>, which edits the live cgroup quota with no restart.
- I verify with <code>docker inspect</code> NanoCpus, <code>docker stats</code>, and the cgroup <code>cpu.stat</code> throttling counters, then profile the process to find the real cause.
- I then codify the limit in Compose or the orchestrator and alert on CPU throttling so it never needs a manual fix again.
Senior hiring managers and bar raisers evaluate how you prioritize during outages. Avoid these common anti-patterns:
- Using only --cpu-shares to stop a hog Shares are relative weights and do nothing on an otherwise idle host, so the container still takes every free core.
- Assuming docker update persists It changes the running container only. Recreating from the Compose file or run command restores the old, unlimited settings.
- Reading 100% in docker stats as the whole machine 100% equals one core, so a multi-threaded process can legitimately show several hundred percent. Compare against the number of CPUs.
- Capping so tightly that latency suffers CFS throttling pauses all threads for the rest of a period, causing latency spikes in request-driven services.