Cluster Roles

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

Action	Permission
View ClusterRoles	`iam:project:infrastructure:kubernetes:read`
Create ClusterRole	`iam:project:infrastructure:kubernetes:write`
Edit ClusterRole	`iam:project:infrastructure:kubernetes:write`
Delete ClusterRole	`iam:project:infrastructure:kubernetes:delete`

Role Types

Type	Description
System	Built-in Kubernetes roles (cannot be deleted)
Custom	User-created ClusterRoles
Aggregated	ClusterRoles 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

Select Cluster

Choose a cluster from the cluster dropdown.

View List

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

Filter and Search

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

How to View ClusterRole Details

Find the ClusterRole

Locate the ClusterRole in the list.

Click ClusterRole Name

Click on the ClusterRole name to open the detail drawer.

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

Click Create ClusterRole

Click the Create ClusterRole button in the page header.

Write YAML

Enter the ClusterRole manifest in YAML format. Key fields:

rules - Array of permission rules
aggregationRule - Optional, for aggregated roles

Create

Click Create to apply the manifest.

How to Edit a ClusterRole

Open Actions Menu

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

Click Edit YAML

Select Edit YAML to open the YAML editor.

Modify Rules

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

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

Open Actions Menu

Click the actions menu on the ClusterRole row.

Click Delete

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

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:

Field	Description
apiGroups	API groups containing the resources (empty string for core API)
resources	Resource types to grant access to
verbs	Actions allowed on the resources
resourceNames	Optional: specific resource names to restrict access
nonResourceURLs	Optional: non-resource URLs (e.g., `/healthz`)

Common Verbs

Verb	Description
`get`	Read a single resource
`list`	List resources
`watch`	Watch for changes
`create`	Create new resources
`update`	Update existing resources
`patch`	Partially update resources
`delete`	Delete resources
`deletecollection`	Delete 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

Role	Description
cluster-admin	Full access to all resources in all namespaces
admin	Full access within a namespace (when bound to namespace)
edit	Read/write access to most resources in a namespace
view	Read-only access to most resources in a namespace
system:node	Permissions for kubelets
system:kube-scheduler	Permissions for the scheduler
system:kube-controller-manager	Permissions 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

User cannot access cluster resources

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

Cannot delete ClusterRole

System roles cannot be deleted (names starting with system:, admin, edit, view)
Verify you have delete permission
Check for finalizers blocking deletion

Aggregated ClusterRole not updating

Verify source ClusterRoles have matching labels
Check aggregationRule selector syntax
Label changes may take a moment to propagate
Verify source ClusterRoles exist

Permission changes not taking effect

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

Wildcard permissions not working as expected

* 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

What is the difference between ClusterRole and Role?

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.

How do I grant cluster-admin access?

Create a ClusterRoleBinding that binds the user/group to the built-in cluster-admin ClusterRole. Be very careful - this grants full access to everything.

What are aggregated ClusterRoles?

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.

Can I use ClusterRoles with RoleBindings?

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.

How do I check what permissions a ClusterRole grants?

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.

What is the principle of least privilege?

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 *.

How do non-resource URLs work?

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.

Can I restrict a ClusterRole to specific namespaces?

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.

Getting Started

Infrastructure

Platform Services

CI/CD & Deployments

Pipeline & Helm

Performance Testing

Security

Mesh Networking

Access Management

Audit & Compliance

Settings

Key Concepts

ClusterRole

Rules

System Role

Aggregation

Required Permissions

Role Types

How to View ClusterRoles

How to View ClusterRole Details

How to Create a ClusterRole

How to Edit a ClusterRole

How to Delete a ClusterRole

Rule Structure

Common Verbs

Example ClusterRoles

Read-Only Cluster Access

Node Administrator

PV Manager

Aggregated ClusterRole

Built-in ClusterRoles

Troubleshooting

FAQ

​Key Concepts

ClusterRole

Rules

System Role

Aggregation

​Required Permissions

​Role Types

​How to View ClusterRoles

​How to View ClusterRole Details

​How to Create a ClusterRole

​How to Edit a ClusterRole

​How to Delete a ClusterRole

​Rule Structure

​Common Verbs

​Example ClusterRoles

​Read-Only Cluster Access

​Node Administrator

​PV Manager

​Aggregated ClusterRole

​Built-in ClusterRoles

​Troubleshooting

​FAQ

Key Concepts

Required Permissions

Role Types

How to View ClusterRoles

How to View ClusterRole Details

How to Create a ClusterRole

How to Edit a ClusterRole

How to Delete a ClusterRole

Rule Structure

Common Verbs

Example ClusterRoles

Read-Only Cluster Access

Node Administrator

PV Manager

Aggregated ClusterRole

Built-in ClusterRoles

Troubleshooting

FAQ