Creating a ClusterRole
What you'll learn: How to define a ClusterRole that grants cluster-wide permissions or creates reusable permission templates across multiple namespaces.
What Is a ClusterRole?
While a Role applies only within a single namespace, a ClusterRole operates at the cluster level. You can use it in two key ways:
- Cluster-wide permissions – Grant access to non-namespaced resources (like nodes, persistent volumes) or all namespaces at once
- Reusable templates – Define a permission set once, then bind it to different namespaces as needed
Think of it like a master key template: instead of cutting a new key for every door (namespace), you create one template and duplicate it wherever needed.
Defining a ClusterRole
A ClusterRole looks nearly identical to a Role, but its scope extends beyond a single namespace:
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: pod-reader
rules:
- apiGroups: [""]
resources: ["pods"]
verbs: ["get", "list", "watch"]
This ClusterRole grants read-only access to Pods across the entire cluster. The structure uses the same rules format you learned when creating Roles: apiGroups, resources, and verbs.
When to Use ClusterRoles
Use a ClusterRole when you need to:
- Access cluster-scoped resources (nodes, persistent volumes, namespaces themselves)
- Grant permissions across all namespaces without duplication
- Create a reusable permission template bound to specific namespaces via RoleBindings
For example, a monitoring tool might need to read Pods in every namespace—perfect for a ClusterRole.
Key Takeaway:
A ClusterRole defines permissions that work cluster-wide or serve as reusable templates; it uses the same rules structure as Roles but operates beyond namespace boundaries.