Overview
What KubeHero is, the problem it solves, what ships in v0.3, and the principles behind it.
KubeHero is open-source Kubernetes observability and FinOps in one install — cost allocation, logs, continuous profiling, eBPF network cost, alerting and rightsizing that actually adjusts, with read-only AI agents on top. It runs in your cluster on AKS, GKE, EKS or any Kubernetes ≥ 1.28, from one Helm chart. Nothing leaves your cluster.
For a five-minute install, jump to the Quickstart.
The problem
To understand a Kubernetes fleet, teams run five tools: a cost allocator, a log store, a continuous profiler, a network observer and an alerting stack. Each has its own agent on every node, its own storage, its own query language and its own UI — and none of them shares a cost model. So none of them can answer the questions that matter at 3 AM:
- What changed? — the log spike, the hot function and the chatty edge are the same incident seen from three tools.
- What does it cost? — per workload, per team, including network and logs, not just CPU and memory.
- What exactly should we do? — a concrete, safe change, not "consider rightsizing".
What KubeHero does
It collects every signal once, stores it once with the same labels (cluster, namespace, workload, team), prices it, and puts a read-only agent on top:
| Signal | What you get | Replaces |
|---|---|---|
| Cost allocation | allocation by any dimension with idle and shared cost, CPU/RAM/GPU/network split, OpenCost-compatible API, FOCUS export, forecasts, efficiency | OpenCost / Kubecost |
| Logs | every container's logs, LogQL, live tail, Drain patterns, log $ per team, Loki push + query API, OTLP logs | Loki + Promtail |
| Profiling | eBPF whole-node CPU profiles with no code changes, pprof scraping, Pyroscope ingest, diff flamegraphs, $/month per function | Pyroscope + agents |
| Network | eBPF flow accounting, a service map with cross-zone and internet egress $, TCP retransmits | a network observability agent |
| Rightsizing | percentile recommendations from measured usage, applied only through human-armed, bounded, reversible policies | VPA / rightsizing tools |
| Alerting | one engine over logs, spend, budgets, anomalies, network $ and cluster events; Slack, PagerDuty, Opsgenie, Teams, Discord, webhooks, Alertmanager | per-tool rule sprawl |
| Agents | briefings (text + voice), Ask KubeHero investigations that cite evidence, an MCP server for Claude — read-only, bring your own key | — |
It keeps what you already run: Prometheus scrapes it, Grafana reads its logs as a Loki datasource, OpenCost clients read its allocation API. See Compatibility.
What ships
One Helm chart installs:
| Component | Runs as | Does |
|---|---|---|
| collector | DaemonSet | cost + usage for its node's pods, container logs, pprof scraping, eBPF flows and CPU profiles, cluster events |
| control-plane | Deployment | ingest, ClickHouse + Postgres, the LogQL / allocation / rightsizing / alerting engines, compatibility APIs |
| operator | Deployment | reconciles BudgetPolicy, CeilingPolicy, RightsizingPolicy — the only component that writes to workloads |
| advisor | Deployment | briefings and investigations; read-only, no Kubernetes credentials |
| pricing-engine | Deployment | live AWS / GCP / Azure price lists |
| dashboard | Deployment | the UI |
| Postgres 18, ClickHouse 26.8 | StatefulSets (embedded) | single-replica stores to start; point at managed stores in production |
Plus the kubehero CLI, which is also the MCP server. See Architecture.
Principles
One store, one cost model
Every signal lands in the same ClickHouse with the same labels, so it can be joined — and so every signal carries a dollar figure. That join is what lets an investigation connect a cost jump to a retry storm in the logs, a hot TLS handshake in a flamegraph and a cross-zone edge in the service map.
Read-only by default
The collector's Kubernetes permissions are read-only. Its eBPF programs observe traffic and CPU; they never drop or alter anything. The advisor has no Kubernetes permissions at all.
Humans arm, the operator acts, everything is reversible
Automation exists — rightsizing that applies, spend ceilings that escalate — but only through policy CRDs a human arms, executed by a deterministic operator in bounded steps, audited, and reversible with kubehero undo. Agents propose; they never hold the pen.
Your data stays in your cluster
No SaaS control plane and no phone-home. The only optional exception is the advisor's LLM brain, which uses your own Anthropic key; without a key nothing leaves.
Compatible beats proprietary
Loki push and query, the OpenCost allocation API, Pyroscope ingest, OTLP logs, Alertmanager and MCP — so adopting KubeHero is a configuration change.
Honest limits
- eBPF needs Linux ≥ 5.8 with cgroup v2 (the default on current AKS, GKE and EKS node images) and a privileged collector; user-space stacks need frame pointers.
- Allocation is an estimate reconciled to node prices, not your cloud invoice; commitments and discounts are not yet replayed onto allocations.
- KubeHero keeps Prometheus as the metrics TSDB and doesn't store distributed traces; trace IDs in logs link out.
What we don't build
- A general-purpose metrics database. Prometheus and Mimir do that well; KubeHero exports to them.
- A tracing backend — OTLP traces are a direction, not a v0.3 feature.
- Automation nobody armed. Guardrails first, always.
- Every cloud. AKS, GKE and EKS are first-class; other clusters work with estimated or annotated node prices.
Deployment shapes
- Single cluster —
helm installputs everything inkubehero-system, with embedded stores. See Quickstart. - Federated — one control plane in a hub cluster; only the collector and operator in each workload cluster, enrolled with a per-cluster token. See Deploy.
- Air-gapped — every image mirrors to your registry; the rules brain needs no network. See Deploy.
Licensing
Apache 2.0 for the CLI, collector, cost model and protos — the code that runs on your nodes. BSL 1.1 for the control plane, operator, advisor, pricing engine and dashboard: source-available and free to self-host. Source: github.com/kubehero-io/platform.