How to Configure Pydantic AI Kubernetes Permissions
You set up pydantic ai kubernetes permissions by linking a service account to a Role. That Role holds the specific rules your AI agent needs to run tasks. Platform teams often start by giving agents wide cluster roles during early tests. Broad roles let an agent change pods, read secrets, or break workloads across namespaces. Scoping these rules early stops an agent from making bad changes in production. How pydantic ai kubernetes permissions work in a cluster A Pydantic AI agent talks to you
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 pydantic ai kubernetes permissions by linking a service account to a Role. That Role holds the specific rules your AI agent needs to run tasks. Platform teams often start by giving agents wide cluster roles during early tests. Broad roles let an agent change pods, read secrets, or break workloads across namespaces. Scoping these rules early stops an agent from making bad changes in production.
How pydantic ai kubernetes permissions work in a cluster
A Pydantic AI agent talks to your cluster through the standard API server. The agent uses tools to check pod health, read logs, or change deployments. Every tool call sends a request to the API server with a token. That token belongs to a dedicated service account made just for the agent.
Kubernetes checks that token against its Role-Based Access Control rules. In this system, all rules are additive and there are no deny rules. You start with zero access and add only the verbs the agent needs. A Role sets rules inside one namespace. A ClusterRole sets rules across the whole cluster or for nodes.
To link the agent to these rules, you create a RoleBinding. A RoleBinding grants the permissions inside one namespace to your agent's service account. If the agent must read items in all namespaces, you use a ClusterRoleBinding. For most AI agents, a single namespace RoleBinding is the safest path.
You also need to watch how the agent uses subresources. In the API, things like pod logs or pod exec paths are subresources. You must list them with a slash in your rules, such as pods/log. If you only grant access to pods, the agent cannot read the logs. If you grant access to the exec subresource, the agent can run shell commands.
What native roles solve and what they leave open
Native roles are great at deciding which service account can call an API endpoint. They stop an agent in a test namespace from deleting apps in production. They also block an agent from reading cluster secrets if you leave secrets out. This setup gives you a strong outer wall for your cluster.
Still, native roles only check who logs in and which API path they hit. They do not inspect what happens inside the request once the call starts. For example, an agent with exec rights can run any command inside a pod. Kubernetes cannot block a bad shell command while allowing a safe check.
AI Agent Permissions + Kubernetes RBAC: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
The same gap appears when an agent reads pod logs or database records. Logs often hold user emails, phone numbers, card numbers, or national IDs. Native roles either let the agent read the whole log or block it all. They cannot mask an email or card number before the text reaches the model.
Scoping agent tools for safer day-to-day operations
To reduce risk, split your Pydantic AI tools by the actions they perform. Give read-only tools a service account that only has get, list, and watch verbs. Keep write actions, like deleting a stuck pod, in a separate tool path. This split keeps a basic check from turning into an accidental outage.
You should also avoid giving agents access to the pod exec subresource by default. When an agent needs to run a check inside a pod, review it first. Static roles alone cannot pause a single command for human approval. Teams need controls that inspect each command and rewrite sensitive fields in results.
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
Should a Pydantic AI agent use a Role or a ClusterRole?
Use a Role and RoleBinding whenever the agent works in a single namespace. Only use a ClusterRole if the agent must inspect nodes or check all namespaces.
How do I let an agent read pod logs without full pod control?
Grant the get and list verbs on the pods/log subresource in your Role. This lets the agent read log output without letting it delete or change pods.
Can Kubernetes RBAC block specific shell commands inside a pod exec session?
No, native RBAC only checks if the account can call the pods/exec subresource. Once the session starts, RBAC cannot filter or block individual shell commands.
Related guides
In this post