The advisor service — LLM or rules-based briefings, proposed actions as guarded CRDs, voice output, and why the AI cannot touch production.

KubeHero ships an advisor service: an agent that reads the same telemetry you do and turns it into three things — a plain-language briefing of what's happening, a ranked list of proposed actions, and the exact CRDs that would carry them out.

The design constraint comes first, because everything else follows from it: the advisor is read-only. It holds no write credentials against your cluster. It cannot evict a pod, patch a Deployment, or cordon a node. Its entire output surface is text and policy objects. Enforcement stays where it has always been — in the deterministic operator, behind humanArm, PDB-aware eviction, and kubehero undo.

What the advisor is

A BSL-licensed service in the control plane that runs a fixed loop:

Observe — query ClickHouse for the window (default 24h): spend, burn rate, utilization percentiles, GPU idle, policy events, anomalies.
Explain — produce a briefing: a short narrative of what changed and what needs a decision, plus a TTS-ready spoken script.
Propose — render each recommendation as a BudgetPolicy, CeilingPolicy, or RightsizingPolicy object with projected $ impact and a risk rating.

Briefings run on a schedule (default daily) and on demand via kubehero brief or the dashboard.

Three tiers

The advisor degrades gracefully. Same loop, same output format, different generator:

Tier	Generator	When
`demo`	Canned briefings over sample data	Evaluation, no cluster required
`rules`	Deterministic rules engine	Default — no API key configured
`llm`	Claude, via your own Anthropic API key	`ANTHROPIC_API_KEY` present

The rules tier is not a stub. It runs the same statistical machinery as the rightsizing engine (p95 over the observation window, headroom, confidence) and templates the briefing from its findings. You get findings, dollar figures, and CRDs without sending a byte to any LLM.

The llm tier hands the same findings to Claude and gets back a better narrative: cross-signal explanations ("the spend bump correlates with the retry storm in checkout, not the new deploy"), prioritization, and a natural spoken script. The proposed CRDs are still produced and validated by the deterministic layer — the model explains and ranks; it does not invent actions.

Configuration

Bring your own Anthropic API key. It lives in your secret manager via external-secrets, like every other credential:

# values.yaml
advisor:
  enabled: true
  tier: llm                     # demo | rules | llm — falls back to rules if the key is absent
  schedule: "0 7 * * *"         # daily briefing, cluster-local time
  anthropic:
    existingSecret: kubehero-advisor   # key: ANTHROPIC_API_KEY
  briefing:
    window: 24h
    maxProposedActions: 5
    voice: true                  # include the TTS-ready spoken script

Or for a quick non-production trial:

kubectl create secret generic kubehero-advisor \
  --namespace kubehero-system \
  --from-literal=ANTHROPIC_API_KEY=sk-ant-...

No key? Leave advisor.anthropic unset. The service logs tier=rules at startup and everything still works.

What leaves your cluster in llm mode: aggregated findings (workload names, utilization stats, dollar figures) sent to the Anthropic API under your key and their data-use terms. Nothing else — no logs, no payloads, no secrets. In rules mode, nothing leaves at all. Air-gapped installs run rules by definition.

Voice briefings

Every briefing includes a spokenScript field — a version written to be heard, not read: numbers rounded, workload names expanded, no tables. The dashboard plays it through the browser's speech synthesis API. No audio leaves your machine; no third-party TTS service is involved.

kubehero brief --cluster prod-us-east-1 --voice

prints the script and, in the dashboard, plays it. Useful on the walk to standup.

The guardrail model

Hard rules, none configurable:

The advisor is read-only. Its ServiceAccount has no write verbs. This is enforced by RBAC, not by prompt.
Every action is a CRD. Proposals materialize as BudgetPolicy / CeilingPolicy / RightsizingPolicy objects — reviewable in the dashboard, diffable in Git, subject to your admission controllers.
The operator enforces, not the model. Applying a proposal hands it to the same reconciler that handles hand-written policies: humanArm: true by default, PDB-aware eviction, bounded change rates (safety.maxChangePerDay), and reversal via kubehero undo <audit-id> within the cooldown window.
Every proposal is audited. Which tier generated it, what data it saw, what it proposed, who armed it, and when — all in the HMAC-signed audit log.

From proposal to change

The full path of one action:

advisor finding              →  RightsizingPolicy (proposed, inert)
kubehero brief / dashboard   →  you read the diff and the risk rating
kubehero apply KH-2107       →  CRD created, humanArm: true, nothing fires
kubehero apply KH-2107 --arm →  operator reconciles: dry-run, then bounded apply
kubehero undo <audit-id>     →  original spec restored, within cooldown

At no point in this chain does the model hold the pen. It drafts; the operator executes; you arm.

Can the AI break prod?

No — and not because the model is well-behaved, but because the system doesn't give it the option:

Can it evict a pod? No. It has no write access. Eviction only happens inside the operator, only via an armed CeilingPolicy, and only PDB-aware.
Can it write a malicious policy? It can propose one. A proposal is an inert object until a human applies and arms it, and it passes through your admission control and Git review like any other manifest.
Can a bad briefing mislead you into a bad decision? This is the real risk, and it's the same risk as any dashboard or teammate. Every number in a briefing links back to the underlying query, so you can check its work.
What if the Anthropic API is down or the key is revoked? The advisor falls back to the rules tier. Briefings keep arriving; they're just drier.
Can it spend my Anthropic credits? Only on the schedule and windows you configure. Token usage is exported as a Prometheus metric (kubehero_advisor_tokens_total).

Where to go next

Concepts — attribution, rightsizing, ceilings: the machinery the advisor drives
CRD reference — the exact schemas every proposal is rendered into
Security — RBAC, audit signing, and what data leaves the cluster
Comparison — how the advisory loop differs from dashboards and autoscalers

Agents & briefings