Kubernetes RBAC: Roles & Bindings Explained

How does Kubernetes RBAC work?

An explanation of how Kubernetes Role-Based Access Control (RBAC) works, including the core concepts and examples.

What is RBAC in Kubernetes?

RBAC is a method of regulating access to the Kubernetes API based on the roles of individual users or service accounts. It uses the rbac.authorization.k8s.io API group to drive authorization decisions.

The system relies on four primary API objects: Role, ClusterRole, RoleBinding, and ClusterRoleBinding.

---

1. Defining Permissions: Roles and ClusterRoles

Roles define what actions (verbs) can be performed on which resources. They contain rules but do not assign them to anyone.

Role (Namespaced)

A Role sets permissions within a specific Namespace. You use it when you want to grant access to resources like Pods or Services within just that one namespace.

Example: A Role named pod-reader that allows reading Pods in the default namespace.

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  namespace: default
  name: pod-reader
rules:
- apiGroups: [""] # "" indicates the core API group
  resources: ["pods"]
  verbs: ["get", "watch", "list"]

ClusterRole (Cluster-Wide)

A ClusterRole is a non-namespaced resource. It is used for:

1. Defining permissions on cluster-scoped resources (like Nodes).
2. Defining permissions on non-resource endpoints (like /healthz).
3. Defining permissions on namespaced resources (like Pods) that you want to grant across all namespaces.

Example: A ClusterRole named secret-reader that allows reading Secrets.

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  # "namespace" omitted since ClusterRoles are not namespaced
  name: secret-reader
rules:
- apiGroups: [""]
  resources: ["secrets"]
  verbs: ["get", "watch", "list"]

---

2. Assigning Permissions: RoleBindings and ClusterRoleBindings

Bindings are the "glue" that assigns a Role to a "Subject" (a User, Group, or Service Account).

RoleBinding (Namespaced Assignment)

A RoleBinding grants the permissions defined in a Role to a user within a specific namespace.

Example: Granting the pod-reader Role to user "jane" in the default namespace.

apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: read-pods
  namespace: default
subjects:
- kind: User
  name: jane # Name is case sensitive
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: Role # this must be Role or ClusterRole
  name: pod-reader # this must match the name of the Role
  apiGroup: rbac.authorization.k8s.io

Advanced Usage: A RoleBinding can also reference a ClusterRole. This is useful for defining a common set of permissions (like "view") globally but granting them only within a specific namespace. For example, giving user "dave" the secret-reader ClusterRole via a RoleBinding in the development namespace allows him to read secrets only in the development namespace.

ClusterRoleBinding (Cluster-Wide Assignment)

A ClusterRoleBinding grants permissions cluster-wide. It binds a ClusterRole to a subject for all namespaces.

Example: Granting the secret-reader ClusterRole to the group "manager" across the entire cluster.

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: read-secrets-global
subjects:
- kind: Group
  name: manager # Name is case sensitive
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ClusterRole
  name: secret-reader
  apiGroup: rbac.authorization.k8s.io

Summary Comparison

Object	Scope	Usage
Role	Namespace	Defines rules for namespace-level resources (e.g., Pods).
ClusterRole	Cluster	Defines rules for cluster-level resources (e.g., Nodes) or common namespace rules.
RoleBinding	Namespace	Grants permissions within a specific namespace (references Role or ClusterRole).
ClusterRoleBinding	Cluster	Grants permissions across the entire cluster (references ClusterRole).