How to Configure Pydantic AI Kubernetes Connect
You set up a pydantic ai kubernetes connect workflow by linking an agent tool to the cluster API. You must give that agent a scoped role so it can run tasks in one namespace. Most teams start by giving the agent a broad role to test fast. That broad role becomes a huge risk when the model can delete pods or read secrets across the whole cluster. How a pydantic ai kubernetes connect setup works In a standard setup, the agent framework defines tools as plain Python functions. The model picks a
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 a pydantic ai kubernetes connect workflow by linking an agent tool to the cluster API. You must give that agent a scoped role so it can run tasks in one namespace. Most teams start by giving the agent a broad role to test fast. That broad role becomes a huge risk when the model can delete pods or read secrets across the whole cluster.
How a pydantic ai kubernetes connect setup works
In a standard setup, the agent framework defines tools as plain Python functions. The model picks a tool and sends structured inputs to match your schema. That function then uses a client library to talk to the Kubernetes API server. The API server checks who the caller is and what rules apply.
Kubernetes uses Role-Based Access Control to manage these rules. In this system, permissions only add rights, and there are no deny rules. A Role sets permissions inside one single namespace. A ClusterRole sets permissions across the whole cluster. It can cover cluster items like nodes, or namespaced items in every namespace.
To link the agent to those rules, you create a binding. A RoleBinding gives permissions inside one namespace. It can point to a Role in that same namespace or to a global ClusterRole. A ClusterRoleBinding gives access across the entire cluster at once. When you set up an agent, you should prefer a RoleBinding in one test or app namespace.
Agents often need to read pod logs or run commands inside a container. Kubernetes treats these actions as subresources in the API URL. The rule names use a slash to show the subresource, such as the pod log path or pod exec path. If an agent needs to read logs for a broken pod, its role must list that subresource rule.
What native roles solve and what they leave open
Native roles and bindings solve the first part of cluster safety. They check which service account or user is calling the API server. They also block the agent from touching namespaces or resource types outside its list. If a role only allows reading pods in a staging namespace, the API server blocks requests to production.
Still, native role checks stop at the API verb and resource level. The API server decides who can log in and call an endpoint. It does not check what individual commands or requests do while in flight. Once a role grants access to the pod exec subresource, the agent can run any shell command inside that container.
Kubernetes RBAC + AI Agent Security: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
Subresource rules also have limits when you try to lock them down by name. In Kubernetes, name limits on create requests only apply to top-level resources, not to subresources. This makes fine control over container commands hard to manage with native roles alone.
Sensitive data in pod logs creates another big gap for engineering teams. When an agent fetches pod logs to fix an error, those logs might hold user data. Raw logs often include emails, phone numbers, card numbers, or national IDs. Native cluster roles cannot scan log text or rewrite matched fields in results before the model reads them.
Finally, teams often share static cluster keys with local agent apps. If a developer stores a long-lived token on a laptop, that key can leak. Native roles cannot pause a risky command for human approval before it hits a live pod.
Add request guardrails and response masking beside Kubernetes
Cluster roles and service accounts govern who reaches the Kubernetes API. Still, a broad role or agent can delete workloads or print sensitive values from ConfigMaps and logs. In practice, hoop.dev runs beside the API server as a sidecar for your Kubernetes API and checks every request and response alongside RBAC.
With hoop.dev Kubernetes controls, guardrails can allow listing Secret names while refusing reads of Secret data before execution. Data masking redacts matched keys in returned JSON responses and log streams in memory. Furthermore, hoop.dev holds SOC 2 Type II and is MIT licensed on GitHub.
Frequently asked questions
How should I scope permissions for a cluster agent?
Start with a Role and a RoleBinding in one single namespace. Avoid ClusterRoleBindings so the agent cannot reach other namespaces or cluster nodes. Only add the exact resource and subresource verbs that the agent tool needs.
Why can my agent run any command when using pod exec?
Kubernetes checks access at the API subresource level, not the shell command level. Once a role grants access to the exec subresource, the API server allows any command inside that pod. You need command checks or pre-flight approvals to limit what runs inside the container.
How do I handle sensitive data in pod logs sent to a model?
Native cluster roles only allow or block access to the log subresource as a whole. To protect data like emails, card numbers, or phone numbers, use data masking. Masking rewrites matched fields in results while the log stream is in flight.
Related guides
In this post