Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Kubernetes RBAC: Role, ClusterRole, RoleBinding, and ServiceAccount

Four objects, additive only, no deny rules. The empty apiGroup that silently voids a rule, why list is not get, and how a default ServiceAccount becomes cluster-admin.

~5 min readKubernetes
#Kubernetes#Security#RBAC
3D illustration of role keycards granting verbs to a service account identity at a cluster gate

Quick Summary

Kubernetes RBAC has four objects. A Role is a set of permissions inside one namespace; a ClusterRole is the same set without a namespace boundary. A RoleBinding grants a Role (or a ClusterRole) to subjects within its own namespace; a ClusterRoleBinding grants a ClusterRole to subjects across the whole cluster. Permissions are purely additive: there are no deny rules, effective access is the union of every binding that matches the user, group, or ServiceAccount.

A rule names apiGroups, resources, and verbs, optionally narrowed by resourceNames and nonResourceURLs. The core API group is the empty string "" — pods, services, configmaps, secrets live there, while deployments are in apps and ingresses in networking.k8s.io. That empty-string detail is the single most common reason a Role "does not work".

ServiceAccounts are the identity workloads use. Every namespace has a default ServiceAccount, and pods get a projected token mounted unless automountServiceAccountToken: false is set. Binding cluster-admin to a default ServiceAccount in a namespace hands every pod in it full cluster control, which is the most frequent privilege-escalation finding in real clusters. This guide covers the object structure, verbs and resources, subjects and groups, aggregation, token mechanics, and the audit commands (kubectl auth can-i) that answer "what can this identity actually do".

Basic Syntax & Core Signatures

yaml
apiVersion: rbac.authorization.k8s.io/v1 kind: Role metadata: { name: pod-reader, namespace: prod } rules: - apiGroups: [""] # core group resources: ["pods", "pods/log"] verbs: ["get", "list", "watch"] - apiGroups: ["apps"] resources: ["deployments"] verbs: ["get", "list", "patch"] resourceNames: ["api"] # only this object - nonResourceURLs: ["/healthz", "/metrics"] verbs: ["get"]
yaml
apiVersion: rbac.authorization.k8s.io/v1 kind: RoleBinding metadata: { name: pod-reader, namespace: prod } subjects: - kind: ServiceAccount name: api namespace: prod - kind: User name: alice@example.com - kind: Group name: devs roleRef: apiGroup: rbac.authorization.k8s.io kind: Role # or ClusterRole, still limited to this namespace name: pod-reader
yaml
apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata: { name: node-reader } rules: - apiGroups: [""] resources: ["nodes", "persistentvolumes"] verbs: ["get", "list", "watch"] - apiGroups: ["storage.k8s.io"] resources: ["storageclasses"] verbs: ["get", "list"]
bash
# Imperative equivalents kubectl create role pod-reader --verb=get,list,watch --resource=pods -n prod kubectl create rolebinding pod-reader --role=pod-reader --serviceaccount=prod:api -n prod kubectl create clusterrole node-reader --verb=get,list --resource=nodes kubectl create clusterrolebinding node-reader --clusterrole=node-reader --group=ops # ServiceAccount tokens kubectl create serviceaccount api -n prod kubectl create token api -n prod --duration=1h # TokenRequest, short-lived kubectl get sa api -n prod -o yaml
bash
# Auditing kubectl auth can-i get pods -n prod kubectl auth can-i '*' '*' --as=system:serviceaccount:prod:api kubectl auth can-i --list -n prod kubectl auth can-i create rolebindings --as=system:serviceaccount:prod:api -n prod kubectl auth reconcile -f rbac.yaml --dry-run=server

Key Comparison Table

ObjectScopeGrantsBindable to
RoleOne namespacePermissions in that namespaceRoleBinding
ClusterRoleClusterCluster-wide or reusable permission setRoleBinding (namespaced) or ClusterRoleBinding
RoleBindingOne namespaceRole or ClusterRole, inside that namespace—
ClusterRoleBindingClusterClusterRole, everywhere—
VerbOperation
getRead one object by name
listRead a collection (kubectl get pods)
watchStream changes (controllers need it)
createCreate objects
updateReplace an object
patchModify fields
deleteDelete one object
deletecollectionDelete many at once
useReference a resource (PSP, SCC)
bind / escalateGrant permissions / bypass escalation checks
impersonateAct as another user or group
Built-in ClusterRoleEffect
cluster-adminEverything, including RBAC
adminFull access in a namespace, including RBAC there
editRead/write workloads, not RBAC
viewRead-only, secrets excluded
system:auth-delegatorToken review and subject access review

Practical Edge Cases & Deep Dives

1. The empty apiGroups for core resources

yaml
# Wrong: pods are not in "v1" as an API group rules: - apiGroups: ["core"] resources: ["pods"] verbs: ["get"] # Right rules: - apiGroups: [""] resources: ["pods"] verbs: ["get"]

kubectl api-resources prints the group for every kind; pods, services, configmaps, secrets, namespaces, nodes, and persistentvolumes all belong to "". Deployments, ReplicaSets, and StatefulSets are in apps; Jobs in batch; Ingresses in networking.k8s.io; RBAC objects in rbac.authorization.k8s.io. A rule with the wrong group is silently inert, and kubectl auth can-i reports "no" without explaining why.

bash
kubectl api-resources | grep -E '^(pods|deployments|ingresses) '

2. list is not implied by get, and watch is what controllers need

bash
$ kubectl auth can-i get pods -n prod yes $ kubectl get pods -n prod Error from server (Forbidden): pods is forbidden: User "..." cannot list resource "pods"

kubectl get pods issues a list, not a series of gets. A subject with only get can read a pod it already knows the name of and cannot enumerate. Controllers and operators additionally need watch on the resources they reconcile, which is why a Role granting get,list lets a human debug but not a controller run.

resourceNames cannot restrict list or watch — the API server has no way to filter a collection by name for authorization — so those verbs with resourceNames are ineffective, and create ignores resourceNames entirely because the name does not exist yet.

3. RoleBinding to a ClusterRole is namespaced

yaml
kind: RoleBinding metadata: { name: view-prod, namespace: prod } subjects: - { kind: Group, name: devs } roleRef: { apiGroup: rbac.authorization.k8s.io, kind: ClusterRole, name: view }

This is the most useful pattern in RBAC: reuse a ClusterRole's permission set (view, edit, admin) inside one namespace. The same roleRef in a ClusterRoleBinding grants it everywhere, including future namespaces, which is the distinction that turns a harmless-looking binding into cluster-wide read access.

4. ServiceAccount tokens: mounted, projected, and minted

bash
$ kubectl exec deploy/api -- cat /var/run/secrets/kubernetes.io/serviceaccount/token | cut -d. -f2 | base64 -d 2>/dev/null | head -c 200 {"aud":["https://kubernetes.default.svc"],"iss":"https://kubernetes.default.svc", "kubernetes.io":{"namespace":"prod","pod":{"name":"api-6d9f"},"serviceaccount":{"name":"api"}}, "exp":1763200000 ...}

Modern clusters project a short-lived, audience-bound token that rotates automatically; it is bound to the pod, expires, and is refreshed. automountServiceAccountToken: false at the pod or ServiceAccount level removes it entirely, which is the right default for workloads that never call the API. The default ServiceAccount is mounted by every pod in the namespace unless disabled, and any binding to it silently applies to all of them.

yaml
apiVersion: v1 kind: ServiceAccount metadata: { name: api, namespace: prod } automountServiceAccountToken: false

5. Escalation prevention and the bind verb

bash
$ kubectl create rolebinding admin --clusterrole=cluster-admin --user=alice -n prod Error from server (Forbidden): rolebindings.rbac.authorization.k8s.io is forbidden: User "bob" cannot create resource "rolebindings" ... cannot escalate to cluster-admin

The API server refuses a binding that grants permissions the creator does not already hold, unless the creator has bind on the target role or the escalate verb on roles. This blocks the obvious privilege escalation and stops a team lead with namespace admin from granting themselves cluster-wide rights. kubectl auth reconcile applies RBAC manifests safely and reports what would change, which is preferable to apply for permission objects.

6. Aggregated ClusterRoles and the built-in groups

yaml
kind: ClusterRole metadata: { name: monitoring } aggregationRule: clusterRoleSelectors: - matchLabels: { rbac.example.com/aggregate-to-monitoring: "true" } rules: [] # filled in automatically by the aggregated rules

The controller populates rules from every ClusterRole carrying the label, so a platform team can add permissions to monitoring by labelling new ClusterRoles. The built-ins use the same mechanism: admin, edit, and view aggregate the system:aggregate-to-* roles.

Groups worth knowing: system:authenticated (everyone with credentials), system:unauthenticated, system:serviceaccounts (all ServiceAccounts), system:masters (cluster-admin by group, unmodifiable through RBAC), and system:serviceaccounts:<namespace> (one namespace's accounts). A ClusterRoleBinding to system:unauthenticated opens the API to the network.

Common Runtime & Configuration Mistakes

SymptomCauseFix
forbidden: cannot list resourceMissing list (only get granted)Add list and watch
cannot get resource "pods"Wrong apiGroups ("core"/"v1")apiGroups: [""]
Permission granted but not effectiveBinding in another namespaceBind in the target namespace
Cluster-wide access where namespace access was intendedClusterRoleBinding instead of RoleBindingUse a RoleBinding
Every pod has API accessdefault ServiceAccount bound, token auto-mountedDedicated SA, automount: false
Controller cannot watchwatch missingAdd watch on the reconciled resources
resourceNames has no effectUsed with list/watch/createRestrict only get/update/patch/delete
cannot escalate to cluster-adminCreating a binding above your own rightsGrant bind/escalate deliberately
system:masters group ignored by RBACHard-coded cluster-admin groupManage membership in the authenticator
Deleted RBAC returns after a whileGitOps reapplies itRemove it from the repository
secrets in the view roleNot included by designCreate a narrow role for secrets
Token not available in the podautomountServiceAccountToken: falseUse TokenRequest and a projected volume

RBAC is a union of allow rules over four object types, and every "it doesn't work" question resolves by naming the identity (user, group, ServiceAccount with its namespace), naming the request (verb plus resource plus API group namespaced correctly), and then finding a binding that connects them. kubectl auth can-i --as=system:serviceaccount:ns:sa <verb> <resource> answers exactly that, which is a faster audit than reading YAML and hoping the union adds up.

Try matching browser tools

All tools

Small utilities that fit Kubernetes work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Kubernetes guides

More in Kubernetes

All Kubernetes guides

The guides filed next to this one in Kubernetes, in library order.