How to Configure Claude Code Kubernetes Credentials
To set up claude code kubernetes credentials, bind a scoped role to a cluster token. Then give that token to the agent through its shell tool or an MCP server. Teams often start by letting the agent use a local admin config file. When roles are too broad, a single prompt can change or delete live workloads. How claude code kubernetes credentials work in practice Claude Code reaches outside systems in two main ways. It can run shell commands through its built-in Bash tool. In manual mode, this
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.
To set up claude code kubernetes credentials, bind a scoped role to a cluster token. Then give that token to the agent through its shell tool or an MCP server. Teams often start by letting the agent use a local admin config file. When roles are too broad, a single prompt can change or delete live workloads.
How claude code kubernetes credentials work in practice
Claude Code reaches outside systems in two main ways. It can run shell commands through its built-in Bash tool. In manual mode, this tool asks for user approval before running most commands. A small built-in list of read-only commands runs without a prompt. The agent can also talk to external tools and APIs through MCP servers. The official docs warn teams to trust each MCP server before use.
When the agent runs a cluster command, it uses local credentials on the machine. Kubernetes controls what those credentials can do through role-based rules. A Role sets permissions inside a single namespace. A ClusterRole sets permissions across the whole cluster or for cluster-wide objects like nodes. In Kubernetes, these rules are purely additive. There are no deny rules in the native role system.
To grant permissions, you create a RoleBinding or a ClusterRoleBinding. A RoleBinding links a user or token to a role in one namespace. A ClusterRoleBinding grants those permissions across every namespace in the cluster. For an AI agent, teams should create a dedicated role with minimal read rights. You can allow reading pod status and pod logs in one test namespace. In the role rules, pod logs use a subresource name written with a slash.
What native cluster roles solve and what they miss
Native cluster roles are great for limiting where an identity can log in. They stop an agent from touching namespaces it has no business seeing. You can block the agent from reading cluster secrets or changing deployment files. If the role only allows read verbs on pods, the agent cannot delete them. You can also leave out the pod exec subresource so it cannot open shells.
Still, native role bindings only check permissions when a request hits the API server. They decide who can call an API endpoint, not what the data inside holds. Once a role allows reading pod logs, the agent can read every log line. App logs often contain sensitive customer details from live traffic. Those logs might include emails, phone numbers, card numbers, or national IDs. Native cluster roles cannot rewrite matched fields in results before the agent reads them.
Claude Code Security + Ephemeral Credentials: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
Static credentials on a laptop also create a long-term key problem. If you store a cluster token on disk, any local process can read it. When an engineer gives the agent a broad role for a quick fix, it stays active. Native roles do not require human approval for individual commands in flight. They also do not tie each agent action back to a single prompt log.
Reducing risk when agents run cluster commands
To keep clusters safe, separate the agent identity from the human engineer identity. Never let an AI coding tool share your personal cluster admin config file. Start with a role that only reads basic pod info in one namespace. Do not grant cluster-wide bindings unless the agent truly needs node data.
Keep the Bash tool in manual mode so a human reviews every shell command. Check which MCP servers the agent uses and how they store cluster tokens. Rotate any stored tokens often so old keys do not linger on laptops. Even with tight roles, remember that read permissions still expose raw log data.
Govern kubectl and API calls in flight
Identity providers and Kubernetes RBAC decide who logs into a cluster. They cannot redact keys inside returned JSON objects or hold a risky delete call for review. By design, hoop.dev sits inline as an open-source proxy, a sidecar for your Kubernetes API, without replacing RBAC. On every production call from an engineer or AI agent, hoop.dev decides to pass, mask, block, or hold it for human approval.
First, hoop.dev guardrails refuse banned methods, paths, or headers before they run or hold risky deletes for review. Next, hoop.dev data masking rewrites sensitive keys in returned Secret, ConfigMap, and log responses in memory, and writes each decision to the audit trail. Explore the repo on GitHub.
Frequently asked questions
How does Claude Code run Kubernetes commands?
The agent runs cluster CLI commands through its Bash tool or uses an MCP server. In manual mode, the Bash tool asks for approval before running non-trivial commands.
Should I use a Role or a ClusterRole for an AI agent?
Use a Role and a RoleBinding whenever possible to keep permissions inside one namespace. Only use a ClusterRole if the agent must inspect cluster-wide objects like nodes.
Can Kubernetes RBAC block specific commands inside a pod exec session?
No, native RBAC only controls who can call the pod exec subresource API. Once the session starts, RBAC cannot filter or approve individual shell commands inside the container.
Related guides
In this post