Before the mechanics, let’s understand the problem limits are solving.

A single physical or virtual machine has a fixed, finite amount of processing power and memory available. Containers running on that machine, unless told otherwise, are free to use as much of that shared processing power and memory as they can get their hands on. This works fine when only one container is running, but becomes a real problem the moment several containers share the same machine — one poorly behaved or unexpectedly busy container can consume so much processing power or memory that every other container on that machine suffers, slows down, or even crashes as a direct result.

This problem even has a common name: the noisy neighbor problem, describing exactly this situation where one workload’s resource usage negatively affects unrelated workloads simply because they happen to share the same underlying machine. Resource limits are Docker’s primary tool for preventing this from happening.

The underlying operating system feature that makes resource limits possible in the first place.

Docker doesn’t invent the mechanism for enforcing resource limits itself. Instead, it relies on a Linux kernel feature called control groups, often abbreviated as cgroups, which allows a group of processes — such as everything running inside a container — to have specific, enforceable limits placed on the resources they’re allowed to consume. When you set a CPU or memory limit on a container, Docker is really just configuring this underlying kernel feature on your behalf.

flowchart LR
    A["You set a CPU or memory limit"] --> B["Docker configures a control group"]
    B --> C["Linux kernel enforces the limit"]
    C --> D["Container's actual resource usage is capped"]
    style D fill:#fef2f2,stroke:#dc2626
        

This is genuinely useful to understand, because it means resource limits aren’t a soft suggestion Docker merely tries to honor — they’re enforced directly by the operating system itself, at a fundamental level, making them a reliable, hard guarantee rather than a best-effort courtesy.

Docker actually offers two related but distinct ways of controlling CPU usage.

CPU control comes in two meaningfully different flavors. A relative share setting doesn’t impose an absolute ceiling at all — instead, it describes a container’s priority relative to other containers whenever processing power is genuinely scarce and being contended for. A hard cap setting, by contrast, imposes a genuine, absolute ceiling on how much processing capacity a container can use, regardless of whether other containers happen to be busy or idle at the time.

This distinction genuinely matters when deciding how to control CPU usage for a given container — a relative share is well suited to expressing “this is more important than that, when things get busy,” while a hard cap is well suited to expressing “this must never use more than a specific amount, no matter what.”

Unlike memory, exceeding a CPU limit doesn’t crash anything — it simply slows things down.

When a container with a hard CPU cap tries to use more processing capacity than its limit allows, the kernel doesn’t terminate anything or produce an error. Instead, it simply prevents the container’s processes from being scheduled to run for brief moments, effectively slowing them down to stay within the allowed ceiling — a behavior called throttling. From the application’s own point of view, it simply appears to run more slowly than it otherwise would, without any crash or visible error being raised.

This is a fundamentally gentler failure mode than what happens when a memory limit is exceeded, which — as the next several chapters explain — behaves in a much more abrupt and consequential way.

A memory limit works very differently from a CPU limit in one crucial way.

Unlike processing power, which can be shared and divided flexibly moment to moment through throttling, memory is a much less flexible resource — once a piece of memory is being genuinely used to hold data, it generally can’t be partially “slowed down” the way processing time can. This fundamental difference is exactly why exceeding a memory limit behaves so differently from exceeding a CPU limit, and why memory limits deserve extra care when being set.

This distinction between a genuine hard limit and a softer reservation mirrors the CPU share-versus-cap distinction from Chapter 3, and understanding both pairs together makes the overall system of resource control feel much more coherent than trying to memorize each setting in isolation.

What actually happens when a container tries to exceed its hard memory limit.

When a container’s processes attempt to use more memory than its configured hard limit allows, the Linux kernel intervenes directly through a mechanism often called the out-of-memory killer, or OOM killer. Rather than allowing the memory request to succeed and risk destabilizing the whole machine, the kernel instead forcibly terminates a process consuming too much memory — typically the very process that triggered the problem — immediately and without warning.

sequenceDiagram
    participant Process as Container's Process
    participant Kernel as Linux Kernel

    Process->>Kernel: Requests more memory than the limit allows
    Kernel->>Kernel: Out-of-memory killer intervenes
    Kernel->>Process: Process forcibly terminated
    Note over Process: No graceful shutdown opportunity given
        

Connecting this behavior back to the container states and exit codes covered elsewhere.

As discussed in the context of container states, an exit code left behind after a container stops is a valuable clue about how and why it stopped. A container terminated by the out-of-memory killer characteristically leaves behind exit code 137, one of the strongest, most reliable signals that a container hit its memory limit and was forcibly killed, rather than exiting through any kind of graceful, voluntary shutdown.

An additional, related setting that affects exactly how much memory pressure a container is allowed to withstand before being killed.

Swap space is a portion of disk storage a machine can use as a slower, overflow extension of its actual memory, when genuine memory runs low. Docker allows configuring how much additional swap space, beyond the hard memory limit itself, a container is permitted to use before the out-of-memory killer intervenes, giving a small amount of additional breathing room under temporary memory pressure, at the cost of significantly slower performance while that swap space is actively being used.

Relying heavily on swap space is generally a sign that a memory limit may be set too tightly for a workload’s genuine needs, since the performance cost of frequently spilling over into slow disk-backed swap is usually far worse than the cost of simply allocating a somewhat higher genuine memory limit in the first place.

Resource limits aren’t only about performance — they’re a genuine security boundary too.

Beyond the everyday “noisy neighbor” problem described in Chapter 1, resource limits also serve a meaningful security function. A container that’s been compromised, or one running unexpectedly malicious code, could otherwise attempt to consume every available resource on a machine deliberately, effectively denying service to every other legitimate workload sharing that same machine. Properly configured resource limits cap the damage any single container — compromised or otherwise misbehaving — can inflict on the rest of the system.

Setting limits well requires actually understanding a container’s genuine, real-world resource usage first.

Choosing sensible CPU and memory limits isn’t a matter of guessing — it depends on observing how much a container genuinely uses under realistic conditions, including its typical usage and its occasional peaks, over a meaningful period of time. Monitoring resource usage continuously, both to inform initial limit choices and to catch a workload’s needs drifting over time, is an essential companion practice to setting limits in the first place.

Limits set without any real observation behind them are essentially a guess, and guesses tend to be wrong in one of two costly directions: either too tight, causing throttling or out-of-memory terminations under genuinely normal conditions, or too loose, providing little real protection against the noisy neighbor problem they were meant to solve in the first place.

A few recurring, sensible strategies teams use when deciding on resource limits.

Seeing how the two kinds of limits relate, side by side, ties the whole picture together.

Seeing these two side by side highlights an important asymmetry worth internalizing: getting a CPU limit slightly wrong tends to produce a recoverable, if annoying, slowdown, while getting a memory limit meaningfully wrong tends to produce an abrupt, unrecoverable crash — which is precisely why memory limits generally deserve more conservative, carefully considered headroom than CPU limits do.

A short checklist for setting resource limits that hold up under real, everyday conditions.

Resource limits are a standard, expected practice across production container deployments in nearly every industry.

As explained in Chapter 4, it’s throttled — gently slowed down by the kernel — rather than crashed or terminated.

As covered in Chapters 6 and 7, the out-of-memory killer forcibly and immediately terminates the offending process, typically leaving behind exit code 137.

As explained in Chapter 5, a limit is a genuine, absolute ceiling, while a reservation is a softer target respected mainly under contention, not strictly enforced.

Not really — as discussed in Chapter 8, heavy swap usage tends to signal the memory limit itself is too tight, since swap comes with a significant performance cost of its own.

Both — as explained in Chapter 9, limits also cap the damage a compromised or misbehaving container can inflict on the rest of a shared machine.

As covered in Chapter 10, base limits on genuinely observed usage data over a meaningful period, rather than guessing, and build in reasonable headroom as discussed in Chapter 11.

CPU and memory limits are Docker’s tools for keeping containers from starving one another out on a shared machine, enforced directly through the Linux kernel’s own control group feature. CPU limits and memory limits, while conceptually similar, behave very differently when exceeded — CPU pressure results in gentle throttling, while memory pressure results in abrupt, forceful termination via the out-of-memory killer, recognizable by exit code 137. Setting these limits thoughtfully, based on genuinely observed usage rather than guesswork, protects both the performance and the security of every workload sharing a machine, making resource limits one of the more consequential, easy-to-overlook details in running containers reliably at any real scale.