Role vs ClusterRole in Kubernetes: Key Differences and Usage

In Kubernetes, a Role defines permissions within a specific namespace, while a ClusterRole grants permissions cluster-wide or across multiple namespaces. Use Role for namespace-scoped access and ClusterRole for broader, cluster-level access.

Quick Comparison

This table summarizes the main differences between Role and ClusterRole in Kubernetes.

Factor	Role	ClusterRole
Scope	Namespace-scoped	Cluster-scoped (all namespaces or cluster resources)
Usage	Grant permissions within a single namespace	Grant permissions across all namespaces or cluster-wide resources
Binding	RoleBinding (within a namespace)	ClusterRoleBinding (cluster-wide) or RoleBinding (namespace-scoped)
Resource Access	Namespace-specific resources only	Namespace and cluster-level resources
Common Use Case	Limit user access to a specific namespace	Administer cluster-wide resources or multiple namespaces

Key Differences

Role is designed to define permissions that apply only inside a single namespace. It controls what actions a user or service account can perform on resources like pods, services, or configmaps within that namespace. This makes Role ideal for limiting access to a specific project or team space.

On the other hand, ClusterRole is not limited to a namespace. It can grant permissions across all namespaces or on cluster-wide resources such as nodes, persistent volumes, or namespaces themselves. This makes ClusterRole suitable for cluster administrators or for roles that need to manage resources beyond one namespace.

When assigning permissions, Role is bound to users or service accounts using a RoleBinding within the same namespace. ClusterRole can be bound using either a ClusterRoleBinding for cluster-wide access or a RoleBinding to grant cluster-level permissions within a specific namespace.

Code Comparison

Here is an example of a Role that allows reading pods in the development namespace.

yaml

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  namespace: development
  name: pod-reader
rules:
- apiGroups: [""]
  resources: ["pods"]
  verbs: ["get", "watch", "list"]

ClusterRole Equivalent

The equivalent ClusterRole grants the same pod read permissions but across all namespaces.

yaml

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: pod-reader
rules:
- apiGroups: [""]
  resources: ["pods"]
  verbs: ["get", "watch", "list"]

When to Use Which

Choose Role when you want to restrict permissions to a single namespace, such as giving a developer access only to their project space.

Choose ClusterRole when you need to manage resources across multiple namespaces or cluster-wide resources, like for cluster administrators or monitoring tools.

Use RoleBinding with Role for namespace-specific access, and ClusterRoleBinding with ClusterRole for cluster-wide access. You can also bind a ClusterRole to a namespace using RoleBinding if needed.

Key Takeaways

Role is namespace-scoped; ClusterRole is cluster-scoped.

Use Role to limit access within one namespace.

Use ClusterRole to grant permissions across all namespaces or cluster resources.

RoleBinding binds Role in a namespace; ClusterRoleBinding binds ClusterRole cluster-wide.

ClusterRole can also be bound in a namespace using RoleBinding for flexible access control.