How to Configure Claude Code Kubernetes Guardrails

Published
Length
3 min read

Luis Felipe Dias

All posts

You set up claude code kubernetes guardrails by pairing local command checks with strict cluster roles. You also limit agent permissions to single namespaces and read-only subresources. Many teams let coding agents use an engineer's personal cluster config file on a laptop. If that engineer holds broad admin rights, the AI agent inherits those same wide rights. One wrong shell command from the agent can then change live pods or read secrets. How native claude code kubernetes guardrails work C

Your coding agents run with your access.

Claude Code reaches prod with a developer's credentials, and approval prompts get clicked through. hoop.dev checks every query, masks sensitive data, and holds risky changes for a human.

You set up claude code kubernetes guardrails by pairing local command checks with strict cluster roles. You also limit agent permissions to single namespaces and read-only subresources. Many teams let coding agents use an engineer's personal cluster config file on a laptop. If that engineer holds broad admin rights, the AI agent inherits those same wide rights. One wrong shell command from the agent can then change live pods or read secrets.

How native claude code kubernetes guardrails work

Claude Code reaches outside systems through Model Context Protocol servers and its built-in Bash tool. In manual mode, the Bash tool asks for human approval before it runs most commands. Only a small built-in list of safe read commands runs without a prompt. When the agent runs cluster commands through the shell, it uses local cluster credentials. Model Context Protocol servers also connect the agent to external tools and APIs.

On the cluster side, native access control relies on Roles and ClusterRoles. A Role sets permissions inside one namespace, while a ClusterRole can span the whole cluster. RoleBindings and ClusterRoleBindings attach those rule sets to a user or a service account. All rules in this system are additive, which means there are no deny rules. You must start with zero permissions and grant only the exact verbs the agent needs.

To keep the agent safe, teams create a dedicated service account for AI tasks. They bind that account to a Role that only allows read verbs on pods. Kubernetes also splits subresources like pod logs and pod exec into separate permission rules. You can grant access to pod logs while leaving out permission for pod exec. This stops the agent from opening a shell inside a running container.

Why native roles and local prompts fall short

Native roles and local approval prompts solve the basic problem of who can log in. They help you block an agent from deleting workloads or touching other namespaces. Local manual mode also gives engineers a chance to check shell commands before they run.

Still, this setup leaves a wide gap during daily work. Prompt fatigue causes busy engineers to approve shell calls without reading every argument closely. Once a Role grants permission to read pod logs, the cluster returns all log text. The native API server does not inspect or mask the text inside those logs. If a pod prints customer emails, phone numbers, or card numbers, the agent gets them. Also, if a role allows pod exec for debugging, RBAC cannot filter the commands inside. The cluster checks the request at the door, not what happens inside the active session.

Claude Code Security + Kubernetes RBAC: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

Steps to tighten agent cluster permissions

First, stop sharing personal admin kubeconfig files with local AI coding tools. Create a separate cluster identity that only holds read permissions in a single test namespace. Second, check every Model Context Protocol server before you connect it to your agent. Use read-only credentials whenever an external server connects to your data stores or cluster APIs.

Third, keep Claude Code in manual approval mode when you work with live clusters. Never allow the Bash tool to run cluster changes or container exec commands without review. Fourth, leave secrets and write verbs out of the Role you bind to the agent. By keeping permissions small and additive, you shrink the blast radius of any bad command.

Check Kubernetes API requests and responses on the wire

Kubernetes RBAC decides who may call the API server. RBAC does not check response payloads or split listing Secret names from reading Secret values when a role grants get access. With hoop.dev, you run an open-source proxy, a sidecar for your Kubernetes API, inline on the API connection. On every kubectl or API call an AI agent or engineer runs against production, hoop.dev decides to pass, mask, block, or hold it for human review.

On each call, hoop.dev guardrails read the method, normalized path, and headers to refuse bad deletes or full Secret reads with a 403 error, or hold risky calls for approval. On the way back, hoop.dev data masking walks JSON responses by key and masks matched values in Secrets, ConfigMaps, and pod logs in memory. View the project on GitHub.

Frequently asked questions

How does Claude Code run commands against a Kubernetes cluster?

Claude Code runs cluster tools through its Bash tool or through Model Context Protocol servers. In manual mode, the Bash tool pauses and asks for your approval before running changes.

Can Kubernetes RBAC block an agent from running specific commands inside a pod?

No, Kubernetes RBAC only controls whether the user can start an exec subresource call. Once the exec session opens, native RBAC cannot filter which shell commands run inside.

How do I let Claude Code read pod logs without giving it container shell access?

Grant the get and list verbs on the pods log subresource in your Role. Leave the pods exec subresource out of the Role since permissions are additive.

The query runs. The emails stay hidden.