Skip to main content
ClusterRoles define permissions that apply across the entire cluster. Unlike namespace-scoped Roles, ClusterRoles can grant access to cluster-scoped resources (nodes, PVs), non-resource endpoints, and resources across all namespaces.

​
Key Concepts

ClusterRole

A cluster-scoped set of permissions defined as rules with verbs, resources, and API groups.

Rules

Permission definitions specifying what actions (verbs) are allowed on which resources.

System Role

Built-in ClusterRoles managed by Kubernetes (prefixed with system:, admin, edit, view).

Aggregation

ClusterRoles that automatically combine rules from other ClusterRoles via label selectors.
ClusterRoles are cluster-scoped resources. They define permissions that can be granted across all namespaces or to cluster-level resources via ClusterRoleBindings.

​
Required Permissions

ActionPermission
View ClusterRolesiam:project:infrastructure:kubernetes:read
Create ClusterRoleiam:project:infrastructure:kubernetes:write
Edit ClusterRoleiam:project:infrastructure:kubernetes:write
Delete ClusterRoleiam:project:infrastructure:kubernetes:delete

​
Role Types

TypeDescription
SystemBuilt-in Kubernetes roles (cannot be deleted)
CustomUser-created ClusterRoles
AggregatedClusterRoles that combine rules from other ClusterRoles
System roles (names starting with system:, cluster-admin, admin, edit, view) are managed by Kubernetes and should not be modified or deleted.

​
How to View ClusterRoles

1

Select Cluster

Choose a cluster from the cluster dropdown.
2

View List

The list shows all ClusterRoles in the cluster (cluster-scoped, no namespace filter).
3

Filter and Search

Use the search box to find ClusterRoles by name. Filter by role type (System, Custom).

​
How to View ClusterRole Details

1

Find the ClusterRole

Locate the ClusterRole in the list.
2

Click ClusterRole Name

Click on the ClusterRole name to open the detail drawer.
3

Review Details

View ClusterRole information including:
  • Overview: Name, type (system/custom), rules count, age
  • Rules: Detailed list of permissions (verbs, resources, API groups)
  • Aggregation Rule: Label selectors for aggregated roles
  • Labels & Annotations: Metadata attached to the ClusterRole

​
How to Create a ClusterRole

1

Click Create ClusterRole

Click the Create ClusterRole button in the page header.
2

Write YAML

Enter the ClusterRole manifest in YAML format. Key fields:
  • rules - Array of permission rules
  • aggregationRule - Optional, for aggregated roles
3

Create

Click Create to apply the manifest.

​
How to Edit a ClusterRole

1

Open Actions Menu

Click the actions menu (three dots) on the ClusterRole row.
2

Click Edit YAML

Select Edit YAML to open the YAML editor.
3

Modify Rules

Edit the ClusterRole rules. Add, remove, or modify permissions as needed.
4

Save

Click Update to apply changes.
Modifying system ClusterRoles can break cluster functionality. Only edit custom ClusterRoles unless you understand the implications.

​
How to Delete a ClusterRole

1

Open Actions Menu

Click the actions menu on the ClusterRole row.
2

Click Delete

Select Delete from the menu (disabled for system roles).
3

Confirm

Confirm the deletion. Any ClusterRoleBindings referencing this role will be affected.
Deleting a ClusterRole removes the permissions it grants. Any subjects bound to this role via ClusterRoleBindings will lose those permissions immediately.

​
Rule Structure

Each rule in a ClusterRole specifies:
FieldDescription
apiGroupsAPI groups containing the resources (empty string for core API)
resourcesResource types to grant access to
verbsActions allowed on the resources
resourceNamesOptional: specific resource names to restrict access
nonResourceURLsOptional: non-resource URLs (e.g., /healthz)

​
Common Verbs

VerbDescription
getRead a single resource
listList resources
watchWatch for changes
createCreate new resources
updateUpdate existing resources
patchPartially update resources
deleteDelete resources
deletecollectionDelete multiple resources
*All verbs (full access)

​
Example ClusterRoles

​
Read-Only Cluster Access

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

​
Node Administrator

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: node-admin
rules:
  - apiGroups: [""]
    resources: ["nodes"]
    verbs: ["get", "list", "watch", "update", "patch"]
  - apiGroups: [""]
    resources: ["nodes/status"]
    verbs: ["get", "update", "patch"]

​
PV Manager

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: pv-manager
rules:
  - apiGroups: [""]
    resources: ["persistentvolumes"]
    verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
  - apiGroups: ["storage.k8s.io"]
    resources: ["storageclasses"]
    verbs: ["get", "list", "watch"]

​
Aggregated ClusterRole

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: monitoring-endpoints
  labels:
    rbac.example.com/aggregate-to-monitoring: "true"
rules:
  - apiGroups: [""]
    resources: ["services", "endpoints", "pods"]
    verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: monitoring
aggregationRule:
  clusterRoleSelectors:
    - matchLabels:
        rbac.example.com/aggregate-to-monitoring: "true"
rules: []  # Rules are automatically filled by aggregation

​
Built-in ClusterRoles

RoleDescription
cluster-adminFull access to all resources in all namespaces
adminFull access within a namespace (when bound to namespace)
editRead/write access to most resources in a namespace
viewRead-only access to most resources in a namespace
system:nodePermissions for kubelets
system:kube-schedulerPermissions for the scheduler
system:kube-controller-managerPermissions for controller manager
Use the built-in admin, edit, and view roles as templates for custom roles, or bind them directly for common use cases.

​
Troubleshooting

  • Verify a ClusterRoleBinding exists binding the user to a ClusterRole
  • Check the ClusterRole has the necessary rules
  • Use kubectl auth can-i to test permissions
  • Verify the subject (user/group/serviceaccount) is correct
  • System roles cannot be deleted (names starting with system:, admin, edit, view)
  • Verify you have delete permission
  • Check for finalizers blocking deletion
  • Verify source ClusterRoles have matching labels
  • Check aggregationRule selector syntax
  • Label changes may take a moment to propagate
  • Verify source ClusterRoles exist
  • RBAC changes are immediate, no restart needed
  • Clear any client-side caching (kubectl, dashboard)
  • Verify the binding is correct (ClusterRoleBinding vs RoleBinding)
  • Check for conflicting roles that might override permissions
  • * in verbs grants all verbs
  • * in resources grants access to all resources in specified apiGroups
  • Empty apiGroups [""] means core API only
  • Use ["*"] for all API groups

​
FAQ

ClusterRole is cluster-scoped and can:
  • Grant access to cluster-scoped resources (nodes, PVs, namespaces)
  • Grant access across all namespaces
  • Grant access to non-resource endpoints
Role is namespace-scoped and only grants access within a single namespace.
Create a ClusterRoleBinding that binds the user/group to the built-in cluster-admin ClusterRole. Be very careful - this grants full access to everything.
Aggregated ClusterRoles automatically combine rules from other ClusterRoles that match specific labels. This allows extending permissions without modifying the original role. The admin, edit, and view roles use aggregation.
Yes. A RoleBinding can reference a ClusterRole, but the permissions are limited to the RoleBinding’s namespace. This is useful for reusing common permission sets across namespaces.
View the ClusterRole details to see all rules. Use kubectl describe clusterrole <name> or click on the ClusterRole in the UI to see the complete rule list.
Grant only the minimum permissions needed. Instead of cluster-admin, create custom ClusterRoles with specific verbs and resources. Use get, list, watch for read-only access instead of *.
Non-resource URLs like /healthz, /api, /metrics are accessed via nonResourceURLs in rules instead of resources. They require explicit rules since they’re not Kubernetes resources.
No. ClusterRoles define permissions, not where they apply. Use RoleBindings (with a ClusterRole reference) to limit permissions to specific namespaces, or use ClusterRoleBindings for cluster-wide access.