For app teams · someone enrolled your namespace

Your pod just got
more headroom.

Headroom now manages your containers' CPU limits — and only the limits. Here's the contract, what you'll see, and the one caveat worth knowing about.

What changed

Your CPU limit is no longer a fixed number. It's your request, plus a fair share of whatever CPU the node hasn't promised to anyone else. Empty node: big limit. Busy node: your request.

What never changes

Your requests, your memory, your scheduling, your bill. Headroom only ever writes limits.cpu — live, via in-place resize, no restarts.

A shrinking limit is normal

It means the node got busier — not an incident. You still have everything you requested, guaranteed by the scheduler and the kernel.

The whole model, one paragraph

Your CPU request is guaranteed. Your CPU limit is your request plus a fair share of whatever CPU the node hasn't promised to anyone else — high on a quiet node, settling back to your request as the node fills. If you need more sustained CPU, raise your request — it buys guaranteed capacity, a bigger kernel share under contention, and a bigger slice of the node's unused CPU, all at once. There is no way to get sustained large CPU by requesting little.

The practical bits

See why your ceiling is what it is

The pod spec is the source of truth — kubectl get pod shows the enforced limit, a status annotation explains it, and every change emits a CPULimitAdjusted event.

kubectl get pod <pod> -o jsonpath=\
'{.metadata.annotations.kube-headroom\.dev/status}' | jq

Opt a pod out

Enrollment is per namespace; excluding one workload is a pod-template label. Guaranteed and BestEffort pods are never managed regardless.

metadata:
  labels:
    kube-headroom.dev/mode: unmanaged

Cap your own ceiling

Pinned parallelism (a GOMAXPROCS-sized service, say)? Tell Headroom never to raise you above it.

metadata:
  annotations:
    kube-headroom.dev/max-cpu: "4"

The one real caveat

Many runtimes size thread pools from a CPU count at boot and never re-read it — a live-raised ceiling won't grow a boot-sized pool. Set your parallelism explicitly, or accept birth-limit sizing. The CPU footguns catalog covers JVM, Go, Python, Node, .NET, Rust, and the ML/GPU stacks, with workarounds for each.

Running VPA? The two compose cleanly — VPA owns requests, Headroom owns limits — as long as VPA is set to controlledValues: RequestsOnly. Using HPA? Structurally unaffected, but unthrottled pods reveal true demand, so review your thresholds. Recipes for both are in the full guide.

READ THE FULL GUIDE IS MY WORKLOAD A FIT?