Giving an AI agent kubectl, without giving it the cluster.
k8s-agent is an open-source Kubernetes dashboard with a built-in Claude Code agent. You can ask it about any resource or have it delete a failing pod, and every action passes through layered checks, with Kubernetes RBAC as the boundary that actually holds.
- Project
- Open source, 2026
- Built with
- Go, Python (FastAPI), Claude Code, Helm
- Runs on
- Kubernetes
§ 01 · Problem
Useful agents need real access. Real access is risky.
AI agents are now good at operating Kubernetes. They can read logs, explain why a deployment is failing, and clean up a crashed pod in seconds. To do that they need kubectl and credentials, and that is the risk: a misunderstood instruction, or a manipulated prompt, can become a real change in a real cluster.
It is tempting to write the rules into the prompt and trust the model to follow them. I wanted the opposite: an agent that is genuinely useful, with limits that still hold if the model does the wrong thing.
§ 02 · Architecture
Three small services, each with only the access it needs.
- Browser UI Static page · nginx No cluster access
- go-svc Go API · policy gate Read-only, cluster-wide
- agent-svc FastAPI · Claude Code Delete pods, allowed namespaces only
- Kubernetes API RBAC Has the final say
- Frontend
- A static browser UI served by nginx. It shows the cluster’s resources and sends questions and actions to the API.
- go-svc (Go)
- Lists cluster information and resources through a read-only ServiceAccount. For agent actions it is the policy gate: it validates and audit-logs every request, then hands allowed ones to the agent. It has no write permissions, so a bug here cannot change the cluster.
- agent-svc (Python, FastAPI)
- Runs Claude Code headless, with kubectl, under its own ServiceAccount. It runs one task at a time with a timeout, and keeps the session so you can ask follow-up questions.
- Helm chart
- Installs all three services with their RBAC, a volume that keeps the Claude Code login across restarts, and an optional ingress.
§ 03 · Guardrails
Five layers of checks. The last one is the one that holds.
-
A policy gate in Go
Every action must be a known action on a valid object in an allowed namespace. kube-system, kube-public, and kube-node-lease are always refused, whatever the configuration. Questions are capped at 2,000 characters. Every decision goes to an audit log, denials as loudly as approvals, recording the length of a question but never its text.
-
Checked again by the agent service
agent-svc repeats every check instead of trusting its caller, so a misconfigured allow-list cannot point the agent at the control plane.
-
A tool allow-list for each action
Each Claude Code run gets only the tools its action needs. A question gets read-only kubectl: get, describe, logs, top, and explain. Only the delete action adds kubectl delete pod. Pipes, redirects, and shell helpers are refused.
-
Managed settings
A managed settings file, which outranks any user setting, allows only kubectl commands and explicitly denies apply, edit, deleting namespaces or nodes, curl, and web access.
-
Kubernetes RBAC: the layer that binds
The agent’s ServiceAccount gets a Role only in the allowed namespaces: delete on pods, read-only access to common workload resources, and no access to Secrets at all. If someone talks the model into printing secret values, the API server refuses. The limit does not depend on the model cooperating.
Every container also runs as a non-root user with a read-only root filesystem, no privilege escalation, and all Linux capabilities dropped. The agent itself is optional: switch it off and k8s-agent is a read-only dashboard.
§ 04 · Run it
One Helm command to install.
Choose the namespaces the agent may act in, then install the chart. The allow-list starts with a single demo namespace.
helm upgrade --install k8sagnet ./charts/k8sagnet \
--namespace k8sagnet --create-namespaceThe README covers building the images, logging the agent in, and running the Go API on its own.
Read the code and README on GitHub