k8s-rbac-companion
A Claude Code plugin for scoping a workload's Kubernetes access to the minimum permissions it actually needs. Reads the workload's code, infers the API access patterns (groups, resources, verbs, subresources), and generates a least-privilege Role/ClusterRole + matching binding as annotated YAML — bound to the workload's ServiceAccount. Apply it with one kubectl command.
What it does
You point it at a workload's directory. It detects the Kubernetes client (client-go, controller-runtime, the kubernetes Python client, or kubectl), infers the API access — which (apiGroup, resource, verb) tuples the code uses, including subresources like pods/log and <resource>/status — asks you three targeted questions (scope, ServiceAccount, and custom-vs-built-in), and emits an RBAC manifest that grants only what the workload actually needs.
The output is a directly-appliable rbac-<sa>.yaml on rbac.authorization.k8s.io/v1, with each rule annotated by an inline # comment citing the source line that justifies it.
Who it's for
Platform and application engineers scoping a workload's Kubernetes access to the minimum necessary permissions — a controller, operator, job, or service that talks to the API server. The pain is well-known:
- RBAC is correct-by-construction only if you get the triple right:
apiGroups + resources + verbs. A wrong apiGroup (e.g. putting ingresses in the core group instead of networking.k8s.io) produces a rule that silently grants nothing — the authorizer matches on group, so the workload gets Forbidden at runtime with no syntax error to catch it.
- The mapping from code to rule is full of non-obvious cases: an informer-backed
List() needs both list and watch; kubectl exec needs create on pods/exec (not get); writing .status needs the <resource>/status subresource; leader election needs leases.
- So teams reach for
cluster-admin or a broad built-in (edit) because hand-authoring a tight Role is tedious and easy to get subtly wrong.
This plugin reads the code and derives the intent — then explains every grant back to you in terms of the line that needed it.
Install in under 5 minutes
You need Claude Code installed and authenticated.
Option A — Marketplace install (recommended)
In any Claude Code session:
- Open
/plugins
- Add marketplace → paste
mjtrapani/k8s-rbac-companion
- Install k8s-rbac-companion
- Restart Claude Code
Option B — Local load (dev / one-off)
git clone https://github.com/mjtrapani/k8s-rbac-companion.git
cd k8s-rbac-companion
claude --plugin-dir .
To verify either install, run /agents — you should see rbac-generator in the list. You can also confirm the knowledge-base skill is active by asking something RBAC-adjacent, like "what verbs does kubectl exec need?" — the rbac-reference skill should auto-load (it's hidden from the slash menu by design — it's a model-invocable knowledge base, not an action command) and inform the answer.
Use it
In Claude Code, from your repo:
/k8s-rbac-companion:rule ./path/to/your/workload
The plugin will:
- Detect the client/framework (e.g.
controller-runtime from go.mod + r.Get(/r.List( call sites)
- Map each API call to
(apiGroup, resource, verb) — including subresources, leader-election leases, and event-recorder events
- Ask you three questions: scope (namespaced
Role vs cluster-wide ClusterRole + namespace), the target ServiceAccount (name + namespace), and role style (a custom least-privilege Role, or bind to a built-in view/edit/admin) — plus a conditional question if it finds a // TODO near K8s calls hinting at planned access
- Write
./rbac-<sa>.yaml to your cwd — the appliable manifest with per-rule rationale as inline comments
- Emit a short summary with the file path and the
kubectl commands to validate, apply, and verify
You can also invoke conversationally:
scope an RBAC role for ./my-controller
Apply and validate end-to-end
The strongest validation: apply the manifest and prove the workload's ServiceAccount can do exactly what it needs — and nothing else.
# 1. Validate the manifest without touching the cluster
kubectl apply -f ./rbac-my-sa.yaml --dry-run=client
# 2. Apply it
kubectl apply -f ./rbac-my-sa.yaml
# 3. Verify what the ServiceAccount can now do
kubectl auth can-i --list --as=system:serviceaccount:my-ns:my-sa
# 4. Negative test — an out-of-scope action should print "no"
kubectl auth can-i delete secrets --as=system:serviceaccount:my-ns:my-sa -n my-ns
# → no
A clean auth can-i --list showing only the intended verbs, and a no on step 4, means the generated rule grants exactly what the workload uses and denies the rest.
