Kubernetes RBAC
Kubernetes RBAC Explained: Roles, RoleBindings and Permissions
Kubernetes RBAC Explained: Roles, RoleBindings and Permissions
bitcodematrix.com | Kubernetes Series
1. Introduction
A Kubernetes cluster is controlled through one API, and everything that happens in it, from creating a Pod to reading a Secret, is a request to that API. Role-Based Access Control (RBAC) decides which of those requests are allowed. It is the main authorization mechanism in almost every production cluster, and it is also one of the most common sources of both security incidents (permissions that are too broad) and frustration (error messages that say "forbidden" without much help).
This article explains RBAC from first principles. You will learn how a request is authorized, what Roles, ClusterRoles and bindings are, how rules are written, which default roles exist, which permissions are dangerous, how to design access for teams, how to review and audit what you have, and how to troubleshoot forbidden errors. It builds on the ServiceAccount and Secrets articles in this series.
2. Where RBAC Fits: Authentication, Authorization and Admission
Every request to the API server passes through three stages in order:
RBAC belongs to the authorization stage. It assumes the caller has already been identified, and it looks only at the attributes of the request: who, which verb, which resource, in which namespace. The API server is normally started with several authorizers, commonly the Node authorizer (which restricts kubelets) followed by RBAC. A request is allowed if any authorizer approves it, and denied if none does.
Two properties of RBAC shape everything that follows:
Default deny. If no rule grants a permission, the action is forbidden.
Purely additive. There are no deny rules. Permissions from all matching roles are combined, so you grant access by adding rules and remove access by removing them.
3. The Four RBAC Objects
RBAC uses four API objects in the group rbac.authorization.k8s.io. Two define permissions, and two attach them to identities:
A simple way to remember it: Roles say what is allowed, and bindings say who gets it and where. A Role or ClusterRole alone grants nothing to anyone until a binding connects it to a subject.
4. Subjects: Who Gets Permissions
A binding lists one or more subjects, each of one of three kinds:
Some built-in groups deserve special attention:
system:authenticated contains every authenticated identity, and system:unauthenticated contains anonymous requests. Binding powerful roles to either is a serious mistake.
system:serviceaccounts and system:serviceaccounts:<namespace> contain all ServiceAccounts, or those of one namespace.
system:masters is special: members are authorized for everything without any RBAC check, and no RBAC rule can restrict them. Treat credentials in this group as a break-glass emergency tool, and do not hand them out to people or tools for daily use.
Names are case-sensitive and must match exactly what the authenticator provides. A mismatch between the group name in a binding and the group claim in a user's token is a classic reason why a correct-looking binding has no effect.
5. Writing Rules: The Anatomy of a Role
A Role or ClusterRole contains a list of rules. Each rule describes a set of allowed actions through four main fields:
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
name: app-operator
namespace: shop
rules:
- apiGroups: [""]
resources: ["pods", "pods/log"]
verbs: ["get", "list", "watch"]
- apiGroups: ["apps"]
resources: ["deployments"]
verbs: ["get", "list", "watch", "update", "patch"]
- apiGroups: [""]
resources: ["configmaps"]
resourceNames: ["app-config"]
verbs: ["get", "update"]
5.1 Verbs
5.2 Subresources
Many everyday operations are permissions on subresources, which must be granted separately from the parent resource:
pods/log is required to read logs with kubectl logs.
pods/exec and pods/attach are required to run commands in a container or attach to it, and pods/portforward to forward ports. These deserve special care, because they give interactive access to workloads.
deployments/scale allows scaling without permission to edit the whole Deployment.
pods/status and similar status subresources are normally used by controllers.
5.3 A ClusterRole Example
Nodes and namespaces are cluster-scoped resources, so permissions on them require a ClusterRole. The example also shows access to non-resource URLs:
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: node-reader
rules:
- apiGroups: [""]
resources: ["nodes"]
verbs: ["get", "list", "watch"]
- nonResourceURLs: ["/healthz", "/livez", "/readyz"]
verbs: ["get"]
Remember that resourceNames works with get, update, patch and delete, but it cannot limit list, watch or create in the way people often expect, so do not rely on it for those verbs.
6. Bindings: Connecting Roles to Subjects
6.1 RoleBinding
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
name: shop-devs-operate
namespace: shop
subjects:
- kind: Group
name: team-shop-devs
apiGroup: rbac.authorization.k8s.io
- kind: User
name: alice@example.com
apiGroup: rbac.authorization.k8s.io
- kind: ServiceAccount
name: ci-deployer
namespace: shop
roleRef:
kind: Role
name: app-operator
apiGroup: rbac.authorization.k8s.io
The binding grants the Role's permissions to all three subjects, only in the namespace shop. Two details matter. First, roleRef is immutable: to point a binding at a different role you must delete and recreate it. Second, for ServiceAccount subjects you specify the namespace of the account, which may differ from the namespace of the binding.
6.2 ClusterRoleBinding
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
name: platform-nodes-read
subjects:
- kind: Group
name: platform-team
apiGroup: rbac.authorization.k8s.io
roleRef:
kind: ClusterRole
name: node-reader
apiGroup: rbac.authorization.k8s.io
6.3 Which Combination Gives What
7. How a Request Is Authorized
For every request, the RBAC authorizer extracts the attributes (the user and groups, the verb, the API group, the resource and subresource, the resource name and the namespace) and evaluates them as follows:
Collect every RoleBinding in the request's namespace and every ClusterRoleBinding in the cluster that has a subject matching the user, one of its groups, or its ServiceAccount.
Load the Role or ClusterRole that each matching binding references.
Check whether any rule in any of those roles matches the verb, the API group, the resource (and subresource), and the resource name if the rule has one.
If at least one rule matches, the request is allowed by RBAC. If none matches, RBAC has no opinion and, with no other authorizer approving it, the request is forbidden.
The rejection message contains the attributes that failed to match, which makes it the best debugging tool you have. For example: User "alice@example.com" cannot list resource "pods" in API group "" in the namespace "shop". Reading it carefully tells you which part of a rule is missing.
8. Aggregated ClusterRoles and Default Roles
8.1 Aggregation
A ClusterRole can be assembled automatically from other ClusterRoles through an aggregationRule with label selectors. The control plane then keeps the rules field up to date. Kubernetes uses this for its user-facing roles, and you can use it to extend them, for example to give the built-in edit role access to your own custom resources:
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: widgets-edit
labels:
rbac.authorization.k8s.io/aggregate-to-edit: "true"
rules:
- apiGroups: ["example.com"]
resources: ["widgets"]
verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
Anyone who holds edit now also has access to the widgets resource. Operators that install custom resource definitions often ship such roles, so that cluster users do not need extra bindings.
8.2 The User-Facing Default Roles
These roles are a sound starting point for people, with one warning: edit is more powerful than it looks. Because it can read Secrets and create Pods that use any ServiceAccount in the namespace, someone with edit can effectively act with the permissions of every ServiceAccount there. Give edit only in namespaces where this is acceptable.
8.3 System Roles
The cluster also contains many roles whose names begin with system:, such as system:node, system:kube-scheduler, system:controller:deployment-controller and system:discovery. Kubernetes components use them. Do not edit or delete them, and do not bind them to ordinary users. The API server reconciles these default roles at start-up and restores any that were changed, unless you opt out by annotation.
9. Privilege Escalation and Dangerous Permissions
9.1 Built-In Escalation Protection
RBAC protects itself against users granting more than they hold:
A user can create or update a Role or ClusterRole only if the user already holds every permission in it, or has the escalate verb on roles.
A user can create a binding only if the user already holds all permissions of the referenced role, or has the bind verb on that role.
Because of this, the ability to edit RBAC objects is not enough by itself to become an administrator. But the escalate and bind verbs bypass the protection, so grant them with great care.
9.2 Permissions That Are More Powerful Than They Look
10. Working With RBAC Day to Day
10.1 Creating Objects
kubectl create role pod-reader --verb=get,list,watch \
--resource=pods -n shop
kubectl create rolebinding dev-pod-reader --role=pod-reader \
--user=alice@example.com -n shop
kubectl create rolebinding ci-deploy --clusterrole=edit \
--serviceaccount=shop:ci-deployer -n shop
kubectl create clusterrole node-reader --verb=get,list,watch \
--resource=nodes
kubectl create clusterrolebinding platform-nodes --clusterrole=node-reader \
--group=platform-team
For anything beyond experiments, store RBAC objects as manifests in version control and apply them through your normal delivery pipeline. The command kubectl auth reconcile applies RBAC manifests in a way that creates missing objects and updates existing roles and bindings safely, and it understands aggregation and the immutable roleRef.
10.2 Testing Permissions
kubectl auth can-i create deployments -n shop
kubectl auth can-i list secrets -n shop --as=alice@example.com
kubectl auth can-i get pods -n shop \
--as=system:serviceaccount:shop:ci-deployer
kubectl auth can-i --list -n shop --as=alice@example.com
kubectl auth can-i get pods -n shop --as=alice@example.com \
--as-group=team-shop-devs
Impersonation with --as requires that you hold the impersonate permission yourself, and it checks what RBAC would decide for that identity. Use --as-group to include group memberships when the permission comes from a group binding. Recent versions of kubectl can also show how the cluster sees your own identity, which is helpful when group claims do not behave as expected.
10.3 Inspecting What Exists
kubectl get roles,rolebindings -n shop
kubectl get clusterroles,clusterrolebindings
kubectl describe rolebinding shop-devs-operate -n shop
kubectl describe clusterrole edit
Kubernetes has no built-in command that answers "who can do X?". For that, use community tools designed for RBAC analysis, or write queries against the output of kubectl get with JSON processing. Examples of such tools are kubectl plugins that list who can perform an action and visualisers of role relationships. Evaluate any tool you use, since it needs read access to RBAC objects.
11. Designing RBAC for Teams
A workable scheme follows a few principles. Use groups, not individual users, so that access follows membership in your identity provider. Use namespaces as boundaries for teams and environments. Reuse ClusterRoles through RoleBindings, so that one definition serves many namespaces. Give applications and pipelines their own ServiceAccounts with minimal roles. An example design looks like this:
A custom Role for a deployment pipeline might be restricted to exactly what it applies:
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
name: deployer
namespace: shop
rules:
- apiGroups: ["apps"]
resources: ["deployments"]
verbs: ["get", "list", "watch", "create", "update", "patch"]
- apiGroups: [""]
resources: ["services", "configmaps"]
verbs: ["get", "list", "watch", "create", "update", "patch"]
- apiGroups: [""]
resources: ["pods"]
verbs: ["get", "list", "watch"]
Notice what is absent: no delete, no Secrets, no RBAC objects, no wildcards. If the pipeline needs more, add it deliberately and review it.
On managed Kubernetes services, the cloud provider's identity system often supplies the authenticated identities and group mappings, and you then bind them with RBAC as usual. Learn how your provider maps cloud identities to Kubernetes users and groups, because that mapping is the first place to look when a user's permissions do not match expectations.
12. Patterns and Anti-Patterns
13. Auditing and Reviewing RBAC
Review the powerful bindings. List who holds cluster-admin and other broad roles, and check that each one is intended.
kubectl get clusterrolebindings -o json | jq -r '
.items[] | select(.roleRef.name=="cluster-admin")
| .metadata.name + " -> "
+ ([.subjects[]? | .kind + ":" + .name] | join(", "))'
Look for risky permissions in custom roles: wildcards, secrets, pods/exec, impersonate, escalate and bind.
Check ServiceAccount permissions for every workload, and remove access that Pods no longer need.
Enable audit logging on the API server. Audit events record who did what, and the authorization decision, which supports investigations and detection of unusual behaviour.
Use policy as code. Admission policies, using tools such as Kyverno or OPA Gatekeeper, can block roles with wildcards, bindings to cluster-admin and similar patterns before they are applied.
Schedule access reviews. Compare actual bindings with the current team structure, and remove people and ServiceAccounts that have left or finished.
Test in CI. Use kubectl auth can-i in pipelines to prove that key identities can do what they should and cannot do what they should not.
14. Hands-On Walkthrough
Create a namespace and a ServiceAccount that stands for a pipeline.
kubectl create namespace rbac-demo
kubectl create serviceaccount ci-bot -n rbac-demo
Check that, at first, it can do nothing.
kubectl auth can-i list pods -n rbac-demo \
--as=system:serviceaccount:rbac-demo:ci-bot
The answer is no, because nothing grants any permission yet.
Create a Role that can read Pods and manage ConfigMaps, and bind it.
kubectl create role ci-role -n rbac-demo \
--verb=get,list,watch --resource=pods
kubectl create rolebinding ci-binding -n rbac-demo \
--role=ci-role --serviceaccount=rbac-demo:ci-bot
Test again, including actions that should be denied.
kubectl auth can-i list pods -n rbac-demo \
--as=system:serviceaccount:rbac-demo:ci-bot
kubectl auth can-i delete pods -n rbac-demo \
--as=system:serviceaccount:rbac-demo:ci-bot
kubectl auth can-i list pods -n default \
--as=system:serviceaccount:rbac-demo:ci-bot
Listing Pods in rbac-demo is now allowed. Deleting Pods is denied because the verb is missing, and listing Pods in another namespace is denied because a RoleBinding applies only inside its own namespace.
Extend the permission by adding a rule, and read the effective list.
kubectl auth can-i --list -n rbac-demo \
--as=system:serviceaccount:rbac-demo:ci-bot
Clean up.
kubectl delete namespace rbac-demo
15. Troubleshooting
Start from the exact forbidden message. It follows a fixed pattern that names the subject, the verb, the resource with its API group, and the namespace. Compare each piece with your role and binding.
16. Best Practices
Follow least privilege: start from nothing and add only the verbs, resources and namespaces that are needed.
Bind to groups from your identity provider, not to individual users, and keep the mapping documented.
Prefer namespaced access: ClusterRoles reused through RoleBindings, and ClusterRoleBindings only when really needed.
Create a dedicated ServiceAccount per workload, grant it only what it uses, and never extend the default account.
Avoid wildcards, and treat secrets, pods/exec, create on pods, impersonate, escalate and bind as high-risk permissions.
Keep cluster-admin and system:masters for very few people and for emergencies.
Manage RBAC as code, with review, tests using kubectl auth can-i, and policy checks in the pipeline.
Enable audit logging, and review access regularly, removing stale bindings and unused ServiceAccounts.
Combine RBAC with admission policies, network policies and Pod security, because RBAC alone does not control what a permitted action can do.
Document your access model, so that every role and binding has an owner and a purpose.
17. Conclusion
RBAC is conceptually small: two kinds of roles that list permitted actions, two kinds of bindings that connect those roles to users, groups and ServiceAccounts, and a default-deny, additive evaluation. Its power and its risks come from the details: which verbs and subresources a rule covers, which scope a binding gives, and which permissions quietly imply others, such as the ability to create Pods or read Secrets.
Design access around groups and namespaces, reuse a few well-understood ClusterRoles, give every workload its own ServiceAccount with minimal rights, treat the dangerous permissions with respect, and review and test continuously. Then RBAC becomes what it should be: a clear, auditable statement of who may do what in your cluster, rather than a source of both outages and exposure.