Skip to content

Kerf documentation

Kerf is open-source, self-hosted Kubernetes rightsizing: it recommends CPU and memory requests and limits from usage history, prices the savings, and applies changes per policy with guardrails and automatic rollback. Start with the README for the overview; this page lists everything else. The same pages are published, with search and a version switch, at getkerf.dev/docs.

Use Kerf

Document What it covers
Quickstart on your laptop One command on kind or k3d: Kerf with demo workloads and recommendations in minutes, what it installed, how to remove it and how to move to a real install
Install on Amazon EKS Prerequisites, AWS resources, the hub and workload clusters, readiness, turning on auto-patch, Argo CD, upgrade, uninstall, troubleshooting
Install on any cluster The same chart on a conformant cluster, with a static price table instead of the AWS price list
Concepts Modes, policies and precedence, apply strategies, guardrails, rollback, HPA coordination, JVM, approve once, GitOps and Argo CD
Operate Upgrade, backup, alerts and dashboards, readiness checks and their fixes, troubleshooting
Reference Generated pages: chart values, custom resources, hub API; plus metrics and events
FAQ and comparison Short answers, and how Kerf differs from VPA, Goldilocks, KRR and the commercial tools
Example values values-hub.yaml, values-spoke.yaml, IAM policies, External Secrets, an Argo CD ApplicationSet
The kerf command-line tool kerf report: recommendations and savings from your existing Prometheus, without installing the hub; install, authentication (including Amazon Managed Service for Prometheus), prices
Helm chart reference global.mode, the umbrella values, opt-in features
Component charts Values of hub, web, pricing, agent, webhook (hub, agent)
Grafana dashboards Overview, opportunities, automation and workload dashboards
Notifications Slack, Teams and signed webhook channels, rules, the weekly digest, retries and metrics
Pricing Where node rates come from (cur, list, spot, static), effective rates from the AWS Cost and Usage Report with Savings Plans and Reserved Instances amortised, its IAM policy and Data Exports settings
Realized savings What applied changes actually saved, kept apart from estimates; the method, with SQL and PromQL to reproduce it
Sign-in and access Required sign-in, users and roles, sign-in protection, bearer tokens for automation, upgrading from anonymous read access
Copy a recommendation as a patch Hand a recommendation over as a strategic merge patch, a kubectl patch command, a Kustomize patch or Helm values, for one workload or a selection
GPU visibility Idle and under-used NVIDIA GPUs: prerequisites (DCGM exporter), the method, the cost, the readiness check
Sign-in and access Required sign-in, users and roles, sign-in with OpenID Connect (Okta, Entra ID, Google, Keycloak, Dex), sign-in protection, bearer tokens for automation, upgrading from anonymous read access
Teams Teams that own workloads (namespace selectors, owner label), team-scoped viewer and operator roles, identity-provider group mappings to teams, savings by team
Node savings Capacity, the node estimate after the recommendations, consolidation blockers with Karpenter and the Cluster Autoscaler
Maintenance and updates Component versions, the check for a new release, turning it off
Changelog What changed in each release and how to upgrade
Security policy How to report a vulnerability

Concepts and contracts

The interfaces between components. Changes to them need a design note (see CONTRIBUTING.md).

Document What it covers
CRDs RightsizingPolicy (modes, strategy, windows, guardrails, rollback) and RightsizingRecommendation, API group kerf.getkerf.dev
Hub API The HTTP API used by the agents, the web UI and automation (OpenAPI 3)
Metrics The kerf_* metrics and the PromQL the recommender runs
Events The audit trail: what the agent decided and did, as sent to the hub
Notification webhook The signed JSON payload (version 1), its headers, retries, and how to verify the signature
Admin area Users, roles, tokens, policies and settings through the API and UI
Readiness Metrics sources (datasources) and the per-cluster readiness checks
Database schema PostgreSQL migrations of the hub

Develop Kerf

Document What it covers
CONTRIBUTING.md Local setup, checks, pull requests
Local environment Three k3d clusters with metrics, Argo CD and sample workloads
Web UI The React app, the mock API, screenshots
End-to-end suite The scenarios and how to run them
Synthetic metrics Long usage histories for testing the recommender
Releasing The release workflow, images, charts, signatures

Design

Document What it covers
Architecture How the hub, agent, webhook and pricing fit together, and the main design choices
Roadmap What comes next
Brand guide Name, positioning, voice, logo, colours; the comparison sources
Screenshots Every UI page in light, dark and tablet layouts (make web-screenshots)