Quickstart
From helm install to every signal in about five minutes — on any Kubernetes 1.28+ cluster.
This page takes you from zero to cost, logs, profiles, the network map and your first guarded policy. For the long form, see the Overview.
Prerequisites
- Kubernetes 1.28+ — AKS, GKE, EKS, or kind / k3d / minikube locally
kubectlpointed at the cluster, and Helm 3.12+- For eBPF profiles and network flows: nodes with Linux ≥ 5.8 and cgroup v2 (the default on current AKS, GKE and EKS images). Without it, everything else still works.
No cluster handy? docker compose up --build -d in the platform repo runs the whole stack with a synthetic three-cluster fleet — then open http://localhost:3001.
Install
helm install kubehero oci://ghcr.io/kubehero-io/charts/kubehero \
-n kubehero-system --create-namespaceThis installs the collector DaemonSet, control plane, operator, advisor, pricing engine and dashboard, plus single-replica Postgres and ClickHouse so it shows real data from the first minute. Auth is on by default. Watch it come up — the control plane waits for its stores:
kubectl -n kubehero-system get pods -wGet your admin token
The chart generates tokens and keeps them in a Secret:
kubectl -n kubehero-system get secret kubehero-control-plane \
-o jsonpath='{.data.admin-token}' | base64 -d; echoOpen the dashboard
kubectl -n kubehero-system port-forward svc/kubehero-dashboard 3001:3001Open http://localhost:3001 and sign in with the token. Cost appears within a minute; logs as soon as containers write; profiles and the service map after the first flush.
Use the CLI
Download kubehero from GitHub Releases, then:
kubectl -n kubehero-system port-forward svc/kubehero-control-plane 8080:8080 &
export KUBEHERO_ENDPOINT=http://localhost:8080
export KUBEHERO_TOKEN=<admin token>
kubehero cost allocation --aggregate namespace --window 24h --idle
kubehero logs '{namespace="default"} |= "error"' --since 1h
kubehero profile targets
kubehero network costs --since 24h
kubehero rightsize
kubehero ask "what changed in spend today?"Your first guarded policy
Start in shadow mode: the operator computes exactly what it would change, and changes nothing.
# rightsizing-shadow.yaml
apiVersion: kubehero.kubehero.io/v1
kind: RightsizingPolicy
metadata:
name: first-look
namespace: kubehero-system
spec:
scope:
namespaceSelector:
matchLabels: { kubernetes.io/metadata.name: default }
mode: shadowkubectl apply -f rightsizing-shadow.yaml
kubectl -n kubehero-system get rightsizingpolicy first-look -o yaml # status.plannedChangesWhen you like what you see, switch to mode: apply and arm it — from the dashboard, or:
kubectl -n kubehero-system annotate rightsizingpolicy first-look kubehero.kubehero.io/armed=trueEvery applied change can be reverted with kubehero undo <change-id>. See Rightsizing.
Optional: Claude as the advisor's brain
Without a key the advisor uses its deterministic rules brain and nothing leaves the cluster. To use Claude with your own key:
kubectl -n kubehero-system create secret generic kubehero-anthropic \
--from-literal=api-key="$ANTHROPIC_API_KEY"
helm upgrade kubehero oci://ghcr.io/kubehero-io/charts/kubehero -n kubehero-system \
--reuse-values --set advisor.anthropic.existingSecret=kubehero-anthropicRead Agents & MCP first — it explains exactly what the model sees.
Optional: Grafana
If kube-prometheus-stack runs in the cluster, Prometheus scrapes KubeHero and the dashboards land in a KubeHero folder. Add KubeHero as a Loki data source to query its logs from Grafana — see Compatibility.
Next
- Production — managed stores, sizing, retention, HA
- Alerting — add channels to the default rules
- Security — verify the read-only guarantees on your cluster