kubernetes

Kubernetes RBAC

Kubernetes RBAC Explained: Roles, RoleBindings and Permissions

By Shubhankar Tripathi • • 5 min read

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:

Stage

Question it answers

Examples

Authentication

Who is making the request?

Client certificates, OIDC tokens, ServiceAccount tokens

Authorization

Is this identity allowed to perform this action?

RBAC, Node authorizer, webhook authorizers

Admission

Should this request be modified or rejected based on policy?

Pod Security admission, validating and mutating webhooks, quota checks

 

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:

Object

Scope

Purpose

Role

One namespace

A set of permissions on resources in that namespace

ClusterRole

Whole cluster

A set of permissions that can cover cluster-scoped resources (such as nodes), non-resource URLs, or namespaced resources in every namespace; also usable as a reusable template for namespaced grants

RoleBinding

One namespace

Grants the permissions of a Role or ClusterRole to subjects, within its own namespace

ClusterRoleBinding

Whole cluster

Grants the permissions of a ClusterRole to subjects across the entire cluster

 

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:

Kind

What it is

Name format in RBAC

User

A person or external system, identified by the authentication layer. Kubernetes has no User object

Whatever the authenticator reports, for example alice@example.com

Group

A set of users, supplied by the authenticator, such as groups from an identity provider

The group name, for example team-shop-devs

ServiceAccount

An identity for Pods, which is a real API object

system:serviceaccount:<namespace>:<name>; in a binding, give the name and namespace separately

 

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"]

Field

Meaning

apiGroups

The API group of the resource. The empty string means the core group (pods, services, configmaps, secrets, nodes, namespaces). Others are named, such as apps, batch, networking.k8s.io and rbac.authorization.k8s.io

resources

The resource types, in plural lowercase form, optionally with a subresource after a slash, such as pods/log or deployments/scale

verbs

The actions that are allowed, listed below

resourceNames

Optional. Limits the rule to specific named objects

nonResourceURLs

ClusterRole only. URL paths that are not API resources, such as /healthz and /metrics

 

5.1 Verbs

Verb

What it allows

get

Read one object by name

list

Read all objects of a type. Note that the response contains the full content of every object, including data in Secrets

watch

Stream changes to objects, required for kubectl get -w and for most controllers. Also exposes full contents

create

Create new objects

update

Replace an existing object

patch

Modify part of an existing object

delete and deletecollection

Remove one object, or many at once

impersonate, bind, escalate, approve, sign

Special verbs on specific resources, described in Section 9; they are powerful

* (wildcard)

Every verb. Avoid it

 

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

Combination

Effect

Role + RoleBinding

Permissions on namespaced resources in that one namespace

ClusterRole + RoleBinding

The ClusterRole is used as a reusable template, but the grant is limited to the binding's namespace. This is the most useful pattern for teams

ClusterRole + ClusterRoleBinding

Permissions on namespaced resources in all namespaces, and on cluster-scoped resources

Role + ClusterRoleBinding

Not possible. A ClusterRoleBinding can reference only a ClusterRole

 

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:

  1. 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.

  2. Load the Role or ClusterRole that each matching binding references.

  3. 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.

  4. 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

ClusterRole

What it grants

cluster-admin

Superuser access to everything. Bound with a ClusterRoleBinding, it gives full control of the cluster. Bound with a RoleBinding, it gives full control over everything in that namespace, including the namespace itself

admin

Intended to be granted in a namespace with a RoleBinding. Read and write on most resources there, including creating Roles and RoleBindings in the namespace, but not changing the resource quota or the namespace object

edit

Read and write on most objects in a namespace, including Secrets and the ability to run Pods as any ServiceAccount of the namespace, but no ability to view or modify Roles and RoleBindings

view

Read-only access to most objects in a namespace. It does not include Secrets, and does not include Roles and RoleBindings

 

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

Permission

Why it is dangerous

get, list or watch on secrets

Reads credentials. List and watch return all values in scope

create on pods

Allows running a Pod as any ServiceAccount in the namespace, mounting its Secrets, and possibly using privileged settings if no admission policy prevents it

create on pods/exec or pods/attach

Interactive access to containers, with their tokens and environment

create on serviceaccounts/token

Mints tokens for any ServiceAccount it covers

impersonate on users, groups or serviceaccounts

Act as another identity, including powerful ones

escalate or bind on roles and clusterroles

Bypasses privilege escalation protection

create, update or patch on roles and bindings

Can change who can do what, within the limits of escalation checks

access to nodes/proxy

Can reach the kubelet API, with possible access to workloads on the node

update on mutating or validating webhook configurations

Can intercept or alter all matching API requests

approve or sign on certificate signing requests

Can issue credentials that the cluster trusts

wildcards for verbs, resources or apiGroups

Include dangerous permissions and any future resource types by accident

 

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:

Persona

Binding

Notes

Application developers of team shop

RoleBinding in namespace shop, group team-shop-devs, ClusterRole edit (or a custom narrower role)

Only their own namespaces; production may use view

Team leads

RoleBinding in team namespaces, ClusterRole admin

Can manage RBAC within the namespace

Auditors and support

ClusterRoleBinding to view, or per-namespace RoleBindings

Read-only; no Secrets by default

Platform team

ClusterRoleBinding to a purpose-built platform role; cluster-admin only for few people

Prefer narrow roles and time-limited elevation

CI/CD deployer

RoleBinding with a custom Role for ServiceAccount ci-deployer

Limited to the resources and namespaces it deploys

Application Pods

Dedicated ServiceAccount, only if the Pod calls the API

Often no binding at all

Emergency access

Break-glass credentials, stored securely and audited

Rarely used, always reviewed

 

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

Anti-pattern

Better approach

Binding cluster-admin to people or applications for convenience

Use namespaced edit or admin, custom narrow roles, and temporary elevation

Granting roles to the default ServiceAccount

Create a dedicated ServiceAccount per workload

Using wildcards for resources, verbs or API groups

List exact resources and verbs, even if it is longer

Binding roles to system:authenticated or system:unauthenticated

Bind to specific groups or identities

A ClusterRoleBinding when a RoleBinding would do

Use a ClusterRole with a RoleBinding to scope it to namespaces

Individual user bindings everywhere

Bind groups from your identity provider

Granting list or watch on secrets to broad groups

Restrict Secret access, and use get with resourceNames where possible

Handing out system:masters credentials

Use cluster-admin through RBAC, with audit trails, and keep masters credentials for break-glass

Editing RBAC objects by hand in production

Manage RBAC through version control and review

Never reviewing old bindings

Run periodic access reviews and remove stale subjects

 

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

  1. Create a namespace and a ServiceAccount that stands for a pipeline.

kubectl create namespace rbac-demo

kubectl create serviceaccount ci-bot -n rbac-demo

  1. 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.

  1. 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

  1. 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.

  1. 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

  1. 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.

Symptom

Likely cause and check

Forbidden although a binding exists

The subject name differs (case, domain, namespace), the group claim is not in the token, or the binding is in another namespace. Verify with kubectl auth can-i using --as and --as-group

Works in one namespace, forbidden in another

A RoleBinding grants access only in its own namespace. Add bindings or use a ClusterRoleBinding if truly needed

Cannot access cluster-scoped resources such as nodes

A namespaced Role cannot grant them. Use a ClusterRole with a ClusterRoleBinding

get works but kubectl get -w fails

The watch verb is missing

Logs or exec fail but get pods works

Subresources need their own rules: pods/log, pods/exec, pods/portforward

Deployments are forbidden although resources contains deployment

Wrong API group or name. Deployments are in apps and the resource name is plural: deployments

Rule with resourceNames does not allow list

resourceNames does not make list or watch work by name. Grant get for a named object, or list for the type deliberately

Error when editing a binding: roleRef cannot be changed

roleRef is immutable. Delete and recreate the binding

Error creating a role: attempting to grant RBAC permissions not currently held

Escalation protection. You need those permissions yourself, or the escalate or bind verb

Aggregated role has no new rules

The labels do not match the aggregationRule selector, or the controller has not updated it yet. Check labels and the resulting rules

ServiceAccount cannot call the API from a Pod

Wrong ServiceAccount in the Pod, token mounting disabled, or a binding with the wrong namespace. Check the Pod spec and the subject

A permission seems to exist but is denied

There may be an admission policy, not RBAC, that rejects the request. Read the message to see which component denied it

Cloud users have unexpected permissions

The cloud identity mapping assigns different groups than expected. Inspect the mapping configuration

 

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.