How to Configure OpenHands Kubernetes Connect
You set up an openhands kubernetes connect workflow by pairing agent credentials with a scoped role. The agent then uses the cluster API to read logs or run pod commands. Many teams start by giving the agent a broad admin role to test fast. This shortcut creates huge risks when an autonomous agent runs the wrong command in production. A single bad prompt or loop can delete workloads or expose private keys across namespaces. Scoping permissions before the agent starts work keeps your cluster safe
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 an openhands kubernetes connect workflow by pairing agent credentials with a scoped role. The agent then uses the cluster API to read logs or run pod commands. Many teams start by giving the agent a broad admin role to test fast. This shortcut creates huge risks when an autonomous agent runs the wrong command in production. A single bad prompt or loop can delete workloads or expose private keys across namespaces. Scoping permissions before the agent starts work keeps your cluster safe from mistakes.
How openhands kubernetes connect works with native roles
Kubernetes controls cluster actions through native roles and bindings on the API server. A Role sets rules for one namespace, while a ClusterRole covers the whole cluster. In this model, permissions only add access, and there are no deny rules. You link the agent identity to a Role using a RoleBinding in that namespace. If the agent needs cluster-wide reach, you use a ClusterRoleBinding instead.
For an openhands kubernetes connect setup, the agent needs specific API rules to work. Reading pod logs or running commands inside a pod uses special API subresources. In role rules, you write these subresources with a slash, like pods and log. You also grant the pods and exec subresource when the agent must run shell commands. You should bind these rules to one namespace so the agent stays in its lane.
What native roles solve and what they leave open
Native roles and bindings do a good job of deciding who can log in. They also limit which namespaces and resource types the agent can touch at a high level. If a role lacks delete rights, the API server blocks the agent from removing pods. This stops many basic mistakes before they harm your uptime.
Still, native role checks stop at the API verb and resource level. Once you grant pod exec rights, Kubernetes does not check the shell commands inside. An agent with exec rights can read local files, dump memory, or call internal services. It can also pull database rows that hold emails, phone numbers, or card numbers. If the agent reads pod logs, those logs might print national IDs in plain text. Native roles also force you to manage static kubeconfig files or long-lived service tokens. Also, standard cluster audit logs record the API call, not the full shell output. Teams need a way to inspect commands in flight and mask sensitive fields in results.
Kubernetes RBAC + End-to-End Encryption: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
Best practices for scoping agent cluster tasks
Start every agent setup with read-only rules in a single test namespace. Give the agent access to read pod status and pod logs first. Do not grant pod exec or secret read rules unless the task requires them. Avoid ClusterRoleBindings for agents that only fix apps in one namespace.
When an agent must run commands or change state, add human checks to the flow. Review the exact command before the agent sends it to the cluster API. Rotate agent credentials often so old tokens do not sit on developer machines. Finally, make sure your logging captures every shell command and rewrites matched sensitive fields.
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 HTTP proxy, a sidecar for your Kubernetes API. The kubectl client changes only the server address it talks to while RBAC stays in place.
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. On the way back, hoop.dev data masking walks JSON responses by key and masks matched values in Secrets, ConfigMaps, and pod logs. Every request and verdict is logged without storing bearer tokens. View the project on GitHub.
Frequently asked questions
How do I limit OpenHands to one Kubernetes namespace?
Create a standard Role and a RoleBinding inside that specific namespace. Do not use a ClusterRoleBinding, because that grants access across all namespaces in the cluster.
Why can the agent see pods but not read their logs?
Pod logs use a separate subresource in the Kubernetes API. You must add the pods and log subresource to your Role rules alongside basic pod read rights.
Can Kubernetes RBAC block specific shell commands inside a pod?
No, native RBAC only checks if the user can call the pod exec subresource. Once the exec session starts, RBAC cannot filter or block individual shell commands.
Related guides
In this post