What Is the Difference Between a RoleBinding and a ClusterRoleBinding?

Detailed Answer

In Kubernetes RBAC, Roles and ClusterRoles define what actions are allowed, while RoleBindings and ClusterRoleBindings determine who gets those permissions and where. The binding is what activates the permission — a Role without a binding does nothing.

RoleBinding

A RoleBinding exists within a namespace and grants the referenced Role's (or ClusterRole's) permissions only within that namespace.

apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: dev-editor
  namespace: development
subjects:
  - kind: User
    name: alice
    apiGroup: rbac.authorization.k8s.io
  - kind: ServiceAccount
    name: ci-deployer
    namespace: development
roleRef:
  kind: Role
  name: namespace-editor
  apiGroup: rbac.authorization.k8s.io

This binding grants both the user alice and the ServiceAccount ci-deployer the permissions defined in the namespace-editor Role, but only within the development namespace.

ClusterRoleBinding

A ClusterRoleBinding is cluster-scoped and grants the referenced ClusterRole's permissions across all namespaces and for cluster-scoped resources.

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: global-secret-reader
subjects:
  - kind: Group
    name: security-team
    apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ClusterRole
  name: secret-reader
  apiGroup: rbac.authorization.k8s.io

This grants the security-team group read access to Secrets in every namespace.

Side-by-Side Comparison

| Aspect | RoleBinding | ClusterRoleBinding | |---|---|---| | Scope | Single namespace | All namespaces + cluster resources | | Has namespace in metadata | Yes (required) | No | | Can reference Role | Yes | No | | Can reference ClusterRole | Yes (scoped to namespace) | Yes (cluster-wide) | | roleRef mutable | No | No |

The Scope Matrix

This table clarifies how the combination of role type and binding type determines effective scope:

| Role Type | Binding Type | Effective Scope | |---|---|---| | Role | RoleBinding | Single namespace | | ClusterRole | RoleBinding | Single namespace (reusable template) | | ClusterRole | ClusterRoleBinding | All namespaces + cluster resources | | Role | ClusterRoleBinding | Invalid — not allowed |

Subjects: Who Gets the Permissions

Both binding types support three subject kinds:

# A specific user
subjects:
  - kind: User
    name: jane
    apiGroup: rbac.authorization.k8s.io

# A group of users
  - kind: Group
    name: developers
    apiGroup: rbac.authorization.k8s.io

# A ServiceAccount (note: namespace is required)
  - kind: ServiceAccount
    name: my-app
    namespace: production

A single binding can list multiple subjects, granting the same permissions to all of them.

Immutable roleRef

One important detail that catches people off guard: the roleRef field is immutable. You cannot change which Role or ClusterRole a binding references after creation.

# This will fail
kubectl patch rolebinding dev-editor \
  --type='json' \
  -p='[{"op": "replace", "path": "/roleRef/name", "value": "new-role"}]'
# Error: roleRef is immutable

To change the referenced role, you must delete and recreate the binding:

kubectl delete rolebinding dev-editor -n development
kubectl create -f updated-rolebinding.yaml

Practical Example: Multi-Namespace Access

Suppose you want to give the platform-team group admin access to three namespaces but not the entire cluster. Use three RoleBindings referencing the built-in admin ClusterRole:

apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: platform-admin
  namespace: app-a
subjects:
  - kind: Group
    name: platform-team
    apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ClusterRole
  name: admin
  apiGroup: rbac.authorization.k8s.io
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: platform-admin
  namespace: app-b
subjects:
  - kind: Group
    name: platform-team
    apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ClusterRole
  name: admin
  apiGroup: rbac.authorization.k8s.io
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: platform-admin
  namespace: app-c
subjects:
  - kind: Group
    name: platform-team
    apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ClusterRole
  name: admin
  apiGroup: rbac.authorization.k8s.io

This is more secure than a ClusterRoleBinding because permissions are limited to exactly the namespaces that need them.

Auditing Bindings

# List all RoleBindings in a namespace
kubectl get rolebindings -n production -o wide

# List all ClusterRoleBindings
kubectl get clusterrolebindings -o wide

# See who is bound to cluster-admin
kubectl get clusterrolebinding -o json | \
  jq '.items[] | select(.roleRef.name=="cluster-admin") | .subjects'

Common Pitfalls

1. Accidentally using ClusterRoleBinding when RoleBinding was intended — this grants cluster-wide access instead of namespace-scoped access.
2. Forgetting that roleRef is immutable — planning binding changes requires delete-and-recreate.
3. Not specifying the namespace on ServiceAccount subjects — the namespace field is required for ServiceAccount subjects in bindings, even when the binding itself is in the same namespace.