kubectl-ro

Read-only Kubernetes access for AI agents and humans.

When you let an LLM explore your cluster, you don't want it running kubectl delete or leaking your secrets. kubectl-ro prevents that.

Build

git clone https://github.com/soyvural/kubectl-ro.git
cd kubectl-ro
go build -o kubectl-ro .

Or install directly:

go install github.com/soyvural/kubectl-ro@latest

Run

1. As a kubectl wrapper

# allowed
kubectl-ro get pods -n kube-system
kubectl-ro logs deployment/my-app --tail=100
kubectl-ro describe svc my-service

# blocked
kubectl-ro delete pod nginx          # BLOCKED: 'delete' is a mutating command
kubectl-ro get secret -o yaml        # BLOCKED: would expose secret values
kubectl-ro exec -it pod -- bash      # BLOCKED: 'exec' is a mutating command

2. As an MCP server for AI

Start the server:

kubectl-ro serve

Or add to Claude Code settings (.claude/settings.json):

{
  "mcpServers": {
    "kubectl-ro": {
      "command": "kubectl-ro",
      "args": ["serve"]
    }
  }
}

This gives AI agents 20 read-only tools: list_pods, list_deployments, get_pod_logs, list_secrets, etc. All secrets are redacted automatically.

3. As a kubectl plugin

If kubectl-ro is on your PATH:

kubectl ro get pods
kubectl ro describe svc my-service

Test

go test ./... -v -race

What gets blocked

All mutating commands: delete, apply, create, edit, patch, exec, scale, drain, cordon, label, annotate, and more.

Secret values are protected. get secrets (table output) is allowed, but -o yaml, -o json, and describe secret are blocked because they expose base64-encoded values. In MCP mode, secret values are replaced with [REDACTED].

Audit log

Every operation is logged to ~/.kubectl-ro/audit.log:

{"timestamp":"2026-03-29T13:04:36Z","interface":"wrapper","action":"get pods","result":"allowed"}
{"timestamp":"2026-03-29T13:04:36Z","interface":"wrapper","action":"delete pod x","result":"blocked","reason":"'delete' is a mutating command"}

Override with KUBECTL_RO_AUDIT_LOG env var.

Verify without executing

kubectl-ro --check get pods           # prints: OK
kubectl-ro --check delete pod nginx   # prints: BLOCKED: 'delete' is a mutating command

License

MIT