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
- Per-Tenant Namespace Isolation: A Role’s permissions never leak outside its own namespace, keeping blast radius minimal in multi-tenant clusters.
- Team-Scoped CI/CD Service Accounts: When a deployment pipeline only needs to manage pods and configmaps in its own namespace, a Role avoids granting any cluster-wide reach.
- Least-Privilege Defaults: Since Kubernetes ships no built-in Roles, authoring one per namespace forces an explicit, minimal grant rather than inheriting a broad default.
ClusterRole
- Access to Cluster-Scoped Resources: Granting permissions on nodes, persistentvolumes, or namespaces themselves requires a ClusterRole, since a Role cannot reference them at all.
- Non-Resource Endpoint Access: Rules covering endpoints like /healthz or /metrics can only live in a ClusterRole, since Roles can’t reference non-resource URLs.
- One Definition Reused Across Namespaces: Defining permissions once and binding them with a RoleBinding in each namespace avoids duplicating the same rules that a Role would require per namespace.
- Composable Permission Sets: aggregationRule lets a ClusterRole auto-combine rules from other labeled ClusterRoles, useful for building up roles like cluster-admin without hand-maintaining a single rule list.