For app teams · quick answers
Short answers to the things teams actually ask when their namespace runs under Headroom — each linking to the full story in the docs.
The node got busier — not an incident. Your limit is your request plus a fair share of whatever CPU the node hasn't promised to anyone else; as neighbors schedule onto the node, that share shrinks toward your request. Your request itself is guaranteed and untouched.
More: the contract · tenant guide
Raise your CPU request — it's self-service and buys three things at once: more guaranteed schedulable capacity, a larger kernel share under contention, and a larger slice of node headroom. There is no way to get sustained large CPU by requesting little. For what number to request, run VPA in recommendation mode and read its suggestion.
More: tenant guide
The pod spec is the source of truth — kubectl get pod shows the enforced limit, the kube-headroom.dev/status annotation explains the math (factor, node headroom, pod count), and every change emits a CPULimitAdjusted event.
More: what you'll see
Label the pod template kube-headroom.dev/mode: unmanaged. Namespace enrollment is your platform team's call; the pod label always wins for a single workload. Guaranteed QoS and BestEffort pods are never managed regardless.
More: opting in and out
Yes — annotate the pod: kube-headroom.dev/max-cpu: "4". Headroom will never raise that pod's limit above 4 cores, useful for pinned-parallelism services that shouldn't be tempted with more.
More: cap your own ceiling
Many runtimes size their thread pools from a CPU count once at startup — JVM ergonomics, Go's automaxprocs, OpenMP/BLAS pools, most ML frameworks — so a live-raised limit doesn't grow them. Set your parallelism explicitly, or accept birth-limit sizing.
More: the CPU footguns catalog (per-runtime workarounds)
No. Headroom only ever writes limits.cpu — live, via in-place resize, no restarts. Requests, memory, placement, and anything billed from requests are untouched.
Yes. HPA computes against requests and is structurally unaffected — though unthrottled pods reveal true demand, so utilization can exceed 100% of request and HPA may scale out earlier (correct, but review thresholds). VPA composes cleanly when set to controlledValues: RequestsOnly: VPA owns requests, Headroom owns limits.
More: the VPA recipe · HPA note
Limits freeze at their last values, and the kernel's cpu.weight keeps sharing CPU fairly by requests. No failure mode is worse than not running Headroom at all — that property is structural, not aspirational.
More: design doc (safety invariants)