What Is the Difference Between a Role and a ClusterRole?

Detailed Answer

Both Role and ClusterRole define a set of RBAC permissions, but they differ in scope. Understanding when to use each is critical for building a secure multi-tenant cluster.

Role: Namespace-Scoped Permissions

A Role exists within a specific namespace and can only grant access to resources in that namespace.

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  namespace: production
  name: deployment-manager
rules:
  - apiGroups: ["apps"]
    resources: ["deployments"]
    verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
  - apiGroups: [""]
    resources: ["pods"]
    verbs: ["get", "list", "watch"]
  - apiGroups: [""]
    resources: ["pods/log"]
    verbs: ["get"]

This Role allows full management of Deployments and read-only access to Pods and their logs, but only in the production namespace. It has zero effect on any other namespace.

ClusterRole: Cluster-Wide Permissions

A ClusterRole is not bound to any namespace. It can grant permissions on:

• Namespaced resources across all namespaces (when used with a ClusterRoleBinding)
• Non-namespaced resources like Nodes, PersistentVolumes, and Namespaces
• Non-resource endpoints like /healthz and /api

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: node-reader
rules:
  - apiGroups: [""]
    resources: ["nodes"]
    verbs: ["get", "list", "watch"]
  - apiGroups: [""]
    resources: ["persistentvolumes"]
    verbs: ["get", "list", "watch"]
  - nonResourceURLs: ["/healthz", "/readyz"]
    verbs: ["get"]

Side-by-Side Comparison

| Aspect | Role | ClusterRole | |---|---|---| | Scope | Single namespace | Cluster-wide | | Metadata namespace field | Required | Not allowed | | Non-namespaced resources | Cannot reference | Can reference | | Non-resource URLs | Cannot reference | Can reference | | Aggregation support | No | Yes (via labels) | | Used with RoleBinding | Yes | Yes (scopes to namespace) | | Used with ClusterRoleBinding | No | Yes |

The ClusterRole + RoleBinding Pattern

One of the most useful patterns in Kubernetes RBAC is defining a ClusterRole once and binding it per namespace with RoleBindings. This avoids duplicating the same Role definition across dozens of namespaces.

# Define the permissions once as a ClusterRole
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: pod-reader
rules:
  - apiGroups: [""]
    resources: ["pods", "pods/log"]
    verbs: ["get", "list", "watch"]
---
# Bind it to the dev namespace for team-alpha
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  namespace: dev
  name: team-alpha-pod-reader
subjects:
  - kind: Group
    name: team-alpha
    apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ClusterRole
  name: pod-reader
  apiGroup: rbac.authorization.k8s.io
---
# Bind the same ClusterRole to the staging namespace
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  namespace: staging
  name: team-alpha-pod-reader
subjects:
  - kind: Group
    name: team-alpha
    apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ClusterRole
  name: pod-reader
  apiGroup: rbac.authorization.k8s.io

This approach is DRY and easier to audit. You update the ClusterRole in one place and every namespace-scoped RoleBinding reflects the change.

Checking Which Resources Are Namespaced

Not sure whether a resource is namespaced? Use this command:

# List all namespaced resources
kubectl api-resources --namespaced=true

# List all cluster-scoped resources
kubectl api-resources --namespaced=false

Common cluster-scoped resources that require a ClusterRole:

• nodes
• persistentvolumes
• namespaces
• clusterroles and clusterrolebindings
• storageclasses
• customresourcedefinitions

Decision Guide

Use a Role when:

• Permissions apply to a single namespace
• You are granting access to namespaced resources only
• You want strict namespace isolation

Use a ClusterRole when:

• You need to grant access to non-namespaced resources (nodes, PVs)
• The same permission set must apply across multiple namespaces
• You are building aggregated roles
• You need access to non-resource URLs

Common Mistake

A frequent mistake is creating a ClusterRole with a ClusterRoleBinding when you only intended namespace-level access. This grants the permissions across the entire cluster. Always verify the binding type matches your intended scope.

# Audit: find all ClusterRoleBindings in the cluster
kubectl get clusterrolebindings -o wide

# Check what a specific ClusterRole allows
kubectl describe clusterrole node-reader