High CPU in Docker? How to limit resources with cgroups

The invisible challenge of resource contention in Docker

When running multiple containers on a single server, infrastructure often suffers from a digital law of the jungle: the application consuming the most CPU ends up starving everything else. In multi-tenant environments, where different services or clients share the exact same hardware, this lack of governance can bring down entire systems overnight. In practice, this means a single poorly optimized process can monopolize processor cores, causing widespread latency and availability drops. To understand the severity of this issue, it is worth noting that, much like we discussed in our analysis of why Kubernetes keeps pods stuck in CrashLoopBackOff, missing resource limits sits at the root of most container infrastructure failures.

What are cgroups and how the Linux kernel handles silicon

Under the hood, Docker did not invent virtualization; it simply packages native Linux operating system technologies, with cgroups (control groups) acting as the core control mechanism. A cgroup is a kernel feature that restricts, accounts for, and isolates physical resource usage—such as CPU, memory, and disk I/O—for a collection of processes. When you start a container, Docker instructs the kernel to place it inside an isolated cgroup tree. In practice, this builds an invisible fence around the process, preventing it from exceeding its allocated hardware slice and ensuring the operating system keeps breathing even under severe stress.

Taming brute force: how CPU shares and periods work

To control container appetites for CPU, Docker offers two main approaches: relative priority and hard processing time limits. The so-called CPU shares define each container's weight when competing for idle processing cycles; if container A has a weight of 1024 and container B has 512, the first will receive twice as much CPU time if the server hits 100% utilization. On the other hand, parameters like cpu-period and cpu-quota allow you to enforce an absolute ceiling. Setting these limits is just as vital as optimizing your build pipelines, a topic we covered thoroughly when explaining how to optimize builds with cache and Docker in continuous integration environments.

Hands-on configuration: setting limits in Docker Compose

The best way to apply this governance in practice is through Docker Compose configuration files, where we can declare limits clearly and versionably. Below, see a practical example of how to restrict CPU usage for a heavy web service, ensuring it uses at most the equivalent of one full core while maintaining a controlled priority.

version: '3.8'services:  api-backend:    image: my-company/api:latest    deploy:      resources:        limits:            cpus: '1.5'            memory: 1024M        reservations:            cpus: '0.5'            memory: 512M

In this configuration snippet, the limits field prevents the container from exceeding one and a half CPU cores, while the reservations field ensures Docker will only start the service if there is at least half a free core available on the host server. This strategy prevents chaotic over-allocation behavior, protecting the overall stability of your homelab or corporate production environment.

Visual tools and real-time monitoring

Writing rules in a configuration file is only the first step; monitoring the behavior of these constraints on a daily basis separates a stable environment from an unpredictable black box. Using visual dashboards like Portainer or lightweight metric tools helps visualize exactly which container is hitting the CPU ceiling configured by cgroups. Furthermore, combining these kernel-level locks with automation and observability solutions ensures you receive alerts before resource starvation causes real downtime for application end-users.

Ensuring long-term stability with hardware governance

Computational resource governance should never be viewed as restrictive bureaucracy, but rather as a foundational pillar of architecture and resilience. By mastering native Linux kernel mechanisms like cgroups, engineers and administrators gain the superpower to predict the behavior of heavy workloads, eliminating unpleasant surprises in production. Whether managing a home server homelab or a corporate microservices fleet, enforcing intelligent limits ensures every application gets exactly what it needs to run efficiently without cannibalizing the surrounding ecosystem.