Headroom documentation

Headroom is a Kubernetes controller that dynamically sets container CPU limits as a function of node slack — recomputed on scheduling events, applied via the GA in-place pod resize subresource. Requests-driven, CPU-only by design, opt-in per namespace.

Start with the page that matches your role:

Architecture

• Design doc — architecture, policy, and rationale. The source of truth; everything else links here.

Operators

• Runbook — preflight, rollout, and day-2 triage.
• Helm migration — moving from kubectl apply -k to the Helm charts.

App teams

• Tenant guide — the contract for teams whose namespaces are enrolled, plus the VPA coexistence recipe and the JVM/quota caveat.

Adoption

• Applicability matrix — when to use Headroom, and when not to: workload classes, scheduler modes, and interactions with HPA/VPA/quota tooling.

Contributing

• Development process — the process doc hub: testing, the kind inner loop, Kubernetes conventions, documentation standards, the technical debt policy, and releasing.

Work is tracked in the repo-local backlog, docs/STATUS.md.