Role vs ClusterRole: Kubernetes RBAC Scope Compared

Sun, 02 Aug 2026 11:24:24 +0900

Overview

Role and ClusterRole are both Kubernetes RBAC objects that define sets of permission rules (verbs on resources), but they differ in scope: a Role only applies within a single namespace, while a ClusterRole is defined once for the whole cluster and can be bound either cluster-wide or scoped down to one namespace. Understanding this distinction is essential for applying least-privilege access control in multi-tenant clusters.

Comparison Diagram

Comparison Table

Aspect	Role	ClusterRole
API object scope	Namespaced object; exists only within one Namespace	Cluster-scoped object; exists once for the entire cluster
Resources it can grant access to	Only namespaced resources (pods, configmaps, secrets, etc.) within its own namespace	Namespaced resources cluster-wide plus cluster-scoped resources such as nodes, persistentvolumes, and namespaces
Non-resource URLs (e.g. /healthz, /metrics)	Cannot reference non-resource URLs	Can include rules for non-resource URLs
Binding object required	RoleBinding only, created in the same namespace	RoleBinding for a namespace-scoped grant, or ClusterRoleBinding for a cluster-wide grant
Effective grant when bound	Permissions always limited to the Role’s own namespace	Spans every namespace when bound via ClusterRoleBinding, or just one namespace when bound via RoleBinding
Reuse across namespaces	Must be duplicated in each namespace that needs the same rules	Defined once, reused across many namespaces or cluster-wide via separate bindings
Aggregation support	None; rules are static within the object	Supports aggregationRule to auto-combine rules from other ClusterRoles by label selector
Typical built-in examples	None shipped by default; teams author their own per namespace	cluster-admin, admin, edit, view, and system: component roles ship as default ClusterRoles

Key Differences

Role is namespace-scoped while ClusterRole is cluster-scoped by definition, regardless of how it’s later bound.
Only ClusterRole can grant access to cluster-scoped resources like nodes or to non-resource URLs such as /metrics.
A ClusterRole can still be restricted to one namespace by binding it with a RoleBinding instead of a ClusterRoleBinding.
ClusterRole supports aggregation to compose permissions from labeled ClusterRoles; Role has no equivalent mechanism.
Kubernetes ships default admin/edit/view permission sets as built-in ClusterRoles, never as Roles.

When to Use Each

Role

Cluster-Administration on IT Comparison

Role vs ClusterRole: Kubernetes RBAC Scope Compared

Overview

Comparison Diagram

Comparison Table

Key Differences

When to Use Each