How to Configure Mastra Kubernetes Credentials
You set up mastra kubernetes credentials by creating a cluster role and binding it to your agent identity. The Mastra app then uses a token to log in and run cluster tasks. Many teams start by giving the agent broad cluster permissions to make setup fast. Broad permissions create big risks when an automated tool runs commands across your cluster. A small mistake in a prompt can delete pods or read secret data across every namespace. How mastra kubernetes credentials work with native roles Kub
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 mastra kubernetes credentials by creating a cluster role and binding it to your agent identity. The Mastra app then uses a token to log in and run cluster tasks. Many teams start by giving the agent broad cluster permissions to make setup fast. Broad permissions create big risks when an automated tool runs commands across your cluster. A small mistake in a prompt can delete pods or read secret data across every namespace.
How mastra kubernetes credentials work with native roles
Kubernetes controls who can do what through its built-in role system. Every rule in this system is additive, which means there are no deny rules. You start with zero access and add rules for each resource the agent needs. A standard Role sets rules inside one single namespace. A ClusterRole sets rules across the whole cluster, including nodes and all namespaces.
To connect these rules to your Mastra agent, you use a binding. A RoleBinding grants permissions inside one namespace for your chosen agent account. A ClusterRoleBinding grants permissions across the entire cluster at once. You can pair a RoleBinding with a ClusterRole to keep a standard rule set inside one namespace. Once bound, the Mastra app reads its credential file or token to talk to the API server.
Some agent tasks need access to subresources, such as reading pod logs or running commands inside a pod. In Kubernetes, you write these subresources with a slash, like pods and log or pods and exec. You must grant permissions for these subresources in your role rules if the agent inspects running containers. Without them, the API server blocks the agent from reading logs or opening a shell.
What native roles solve and what they leave open
Native roles and bindings do a good job of deciding who can log in to the cluster. They let you limit a Mastra workflow to one namespace instead of the whole cluster. They also let you separate read rules on pods from write rules on deployments. This setup stops an unauthorized app from reaching the API server at all.
Still, native cluster credentials only check permissions when the API call starts. Once an agent has permission to exec into a pod, the role cannot inspect the shell commands inside. If an agent can read secrets or logs, the role does not filter out emails, phone numbers, or card numbers. Also, static credential files stored on developer laptops or build servers can leak if someone copies them. Teams need a way to control each command in flight and keep raw keys off client machines.
Ephemeral Credentials + Kubernetes RBAC: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
Steps to scope your agent permissions
Start by listing the exact API resources your Mastra agent must read or change. Create a dedicated identity for the agent instead of sharing a human admin account. Write a Role inside a single target namespace rather than a cluster-wide rule whenever you can. Leave out pod exec and secret read rules unless the agent task truly needs them.
Bind the Role to the agent identity with a RoleBinding in that same namespace. Test the Mastra workflow with a small task to check that the rules work as expected. Review your bindings often and remove any rules the agent no longer uses. Rotate the token on a set schedule so old credentials do not stay active forever.
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
Can I add a deny rule to block my Mastra agent from one secret?
No, Kubernetes role rules are only additive and do not support deny rules. To block access to a resource, you must leave it out of the granted role rules.
Should I use a RoleBinding or a ClusterRoleBinding for Mastra?
Use a RoleBinding whenever the agent only works inside one namespace. Use a ClusterRoleBinding only when the agent must inspect nodes or work across every namespace.
How do I let Mastra read pod logs without giving full pod control?
Grant read access to the pod log subresource in your role rules. This lets the agent fetch logs without giving it permission to delete pods or run exec commands.
Related guides
In this post