kubezilla

README

KubeZilla 🦖

The autonomous Kubernetes SRE you can actually trust to act — because it's caged.

Detect → Diagnose → Plan → Remediate → Verify. Fully autonomous. Every action runs inside a kernel-isolated Agent Sandbox — never with cluster-admin on your nodes.

Quickstart · What it does · Architecture · Safe Autonomy · Roadmap

---

🦖 Goal

Diagnosing a broken cluster is only half the job — someone still has to fix it, by hand, often at 3am. True autonomy means letting an agent close that loop: detect the problem, reason about the root cause, apply the fix, and confirm it worked.

The thing standing in the way is trust. You do not want an LLM holding cluster-admin, free-handing kubectl delete against prod.

KubeZilla makes autonomy safe. It runs the full SRE loop on its own, but every diagnostic command and every line of LLM-generated remediation executes inside a gVisor/Kata-isolated Agent Sandbox with a scoped, time-boxed ServiceAccount, a dry-run gate, a full audit trail, and automatic rollback. The blast radius is the sandbox — not your node.

Reason freely. Act minimally. The model sees everything; the executor can touch almost nothing.

---

✨ What KubeZilla does

• 🔍 Detects & diagnoses — read-only analyzers scan pods, deployments, events and more, then a pluggable LLM ranks the most likely root cause with a confidence score.
• 🛠️ Remediates autonomously — turns the diagnosis into a typed remediation plan (not free-text shell), then applies it and verifies the result.
• 🔒 Acts inside a sandbox — every action runs kernel-isolated (gVisor/Kata) with ephemeral, least-privilege credentials that expire in minutes. KubeZilla's own identity is read-mostly and never touches your workloads directly.
• ↩️ Rolls back automatically — every action ships its own undo; if the fix doesn't verify, KubeZilla reverts it and escalates. No rollback, no apply.
• 🎚️ Stays in your control — dial autonomy from "diagnose only" to "fully autonomous," with policy guardrails and human approval gates.
• 🧾 Leaves an audit trail — every decision (signals → hypothesis → plan → action → result) is recorded and replayable.
• 🧠 Works with your model — Claude (default), OpenAI, Gemini, or a local Ollama. Never locked in.
• ⚙️ CLI and GitOps-native — a one-command CLI to start in 60 seconds, plus CRDs and an operator for declarative, in-cluster autonomy.

---

🚀 Quickstart

# Install
go install github.com/ajeetraina/kubezilla/cmd/kubezilla@latest

# Point at your cluster + pick a model (Claude by default)
export ANTHROPIC_API_KEY=sk-ant-...
export KUBEZILLA_MODEL=claude-opus-4-8

# 1. Scan — a read-only diagnosis of your cluster
kubezilla analyze

# 2. Let it propose a fix — dry-run, nothing touches the cluster yet
kubezilla diagnose --namespace payments

# 3. Full autonomous loop, sandboxed, with an approval gate before apply
kubezilla agent run --namespace payments --autonomy assisted

Example:

🦖 KubeZilla — scanning namespace "payments"

  ● CrashLoopBackOff  payments/checkout-7f9c   (restarts: 142)
    └─ root cause: liveness probe hits :8080/health, container listens on :3000
    └─ confidence: 0.93

  Proposed remediation (sandboxed, dry-run):
    patch deployment/checkout  .spec...livenessProbe.httpGet.port  8080 → 3000

  Sandbox:  gvisor · sa/kubezilla-checkout-remediator (TTL 5m, verbs: get,patch on deployments/checkout)
  Verify:   rollout healthy AND 0 restarts in 120s, else auto-rollback

  Approve? [y/N]

Don't have a cluster? kubezilla demo spins up a broken workload in kind so you can watch KubeZilla fix it end-to-end.

---

🧠 How it works

        ┌──────────────────────────────────────────────────────────────┐
        │                        KubeZilla Agent                        │
        │   observe → reason (LLM) → plan → POLICY GATE → act → verify   │
        └───────┬───────────────────────────────┬──────────────────────┘
                │ read-only                      │ every action
                ▼                                ▼
        ┌───────────────┐                ┌──────────────────────────┐
        │  Analyzers    │                │   Agent Sandbox (SIG)    │
        │ (k8s, events, │                │  gVisor / Kata isolation │
        │  metrics)     │                │  scoped SA · TTL · audit │
        └───────────────┘                └──────────────────────────┘

1. Observe — analyzers scan resources, events, and metrics (read-only).
2. Reason — a pluggable LLM correlates signals into a ranked root-cause hypothesis.
3. Plan — KubeZilla emits a structured, typed RemediationPlan (not free-text shell).
4. Policy gate — OPA/Rego + autonomy level decide: auto-apply, require approval, or refuse.
5. Act — the plan executes inside an Agent Sandbox with a minimal, time-boxed ServiceAccount.
6. Verify — success criteria are checked; on failure KubeZilla auto-rolls-back and escalates.

Full design: docs/architecture.md · safety model: docs/safe-autonomy.md.

---

🎚️ Autonomy levels

KubeZilla never makes you choose between "useless" and "terrifying." Dial it in:

Level	Behavior	Use it for
observe	Diagnose only — never mutates	First day on a new cluster
assisted	Propose + apply on approval (default)	Prod, with a human in the loop
auto-safe	Auto-apply allow-listed low-risk fixes	Restarts, probe fixes, HPA nudges
autonomous	Full loop within policy budget	Dev/staging, blue-green, on-call relief

---

📦 Install (Operator / GitOps)

helm repo add kubezilla https://ajeetraina.github.io/kubezilla
helm install kubezilla kubezilla/kubezilla -n kubezilla-system --create-namespace

apiVersion: agents.kubezilla.dev/v1alpha1
kind: Agent
metadata:
  name: payments-sre
spec:
  scope:
    namespaces: ["payments"]
  autonomy: assisted
  model: claude-opus-4-8
  sandbox:
    runtime: gvisor          # or kata
    ttlSeconds: 300
  policyRef: payments-guardrails

---

🗺️ Roadmap

KubeZilla is built in the open and aims for CNCF Sandbox donation. See ROADMAP.md.

🤝 Contributing

We ❤️ contributors — good first issues are labeled and mentored. Read CONTRIBUTING.md and our Code of Conduct.

📄 License

Apache 2.0 — see LICENSE.

_{Built for the Kubernetes community. 🦖 Tame the chaos.}