Role vs ClusterRole
What you'll learn: You'll discover when to use namespace-scoped Roles versus cluster-wide ClusterRoles to control access in Kubernetes.
The Fundamental Difference
In Kubernetes RBAC, Roles and ClusterRoles both define sets of permissions, but they differ dramatically in their scope:
- A Role grants permissions within a specific namespace. Think of it as a department manager who can only make decisions within their own department.
- A ClusterRole grants permissions cluster-wide or for non-namespaced resources. This is like a company executive who has authority across all departments.
When to Use Each
Use a Role when you need to control access to resources within a particular namespace. For example, allowing developers to manage Pods and Services only in the "development" namespace:
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
namespace: development
name: pod-manager
rules:
- apiGroups: [""]
resources: ["pods"]
verbs: ["get", "list", "create"]
Use a ClusterRole when you need:
- Cluster-wide access to namespaced resources (like viewing Pods across all namespaces)
- Access to cluster-scoped resources (like Nodes, PersistentVolumes, or Namespaces themselves)
- A reusable template that can be bound at different namespace levels
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: node-reader
rules:
- apiGroups: [""]
resources: ["nodes"]
verbs: ["get", "list"]
Scope Analogy
Think of Roles as room keys in a hotel—they only open doors in specific hallways. ClusterRoles are master keys that can potentially open any door in the entire building, depending on how you use them.
Key Takeaway: Use Roles for namespace-specific permissions and ClusterRoles for cluster-wide access or when managing non-namespaced resources like Nodes and PersistentVolumes.