2.5 ClusterRoles & ClusterRoleBindings

ClusterRoles & ClusterRoleBindings

While Role and RoleBinding operate strictly within the boundaries of a single namespace, enterprise Kubernetes administration requires access management for cluster-scoped resources (such as Nodes, PersistentVolumes, StorageClasses, and Namespaces), uniform policy definitions across multi-tenant environments, and API server endpoints outside the resource tree.

ClusterRole and ClusterRoleBinding provide this cluster-wide RBAC capability.

---

1. Cluster-Scoped vs. Namespace-Scoped Resources

Before designing an RBAC policy, an administrator must know whether the target resource is cluster-scoped or namespace-scoped. The kubectl api-resources command provides instant inspection:

# List all cluster-scoped resources (namespaced = false)
kubectl api-resources --namespaced=false

# List all namespace-scoped resources (namespaced = true)
kubectl api-resources --namespaced=true

---

2. The Two Architectural Patterns of ClusterRoles

A ClusterRole is an unbound set of permissions. The critical design decision is how it is bound to a subject:

+---------------------------------------------------------------------------------------------------------+
|                                THE TWO CLUSTERROLE BINDING PATTERNS                                     |
|                                                                                         |
|   PATTERN 1: CLUSTER-WIDE ACCESS (ClusterRole + ClusterRoleBinding)                                     |
|   +--------------------------+          +-------------------------------+         +-----------------+   |
|   |       ClusterRole        |          |      ClusterRoleBinding       |         |     Subject     |   |
|   |   (e.g., node-reader)    |<---------| (Bound Globally)              |<--------|  (User: auditor)|   |
|   +--------------------------+          +-------------------------------+         +-----------------+   |
|                |                                                                                        |
|                v                                                                                        |
|   [Grants access to Nodes, PVs, and resources across ALL namespaces globally]                           |
|                                                                                                         |
|   ===================================================================================================   |
|                                                                                                         |
|   PATTERN 2: NAMESPACE-SCOPED REUSE (ClusterRole + RoleBinding)                                         |
|   +--------------------------+          +-------------------------------+         +-----------------+   |
|   |       ClusterRole        |          |      RoleBinding (ns: dev)    |         |     Subject     |   |
|   |      (e.g., 'edit')      |<---------| (Bound ONLY in 'dev')         |<--------|  (User: dev-bob)|   |
|   +--------------------------+          +-------------------------------+         +-----------------+   |
|                |                                                                                        |
|                v                                                                                        |
|   [Grants 'edit' permissions ONLY within the 'dev' namespace; ZERO access outside 'dev']                |
+---------------------------------------------------------------------------------------------------------+

Pattern 1: ClusterRole + ClusterRoleBinding (Global Cluster Access)

• Grants permissions to cluster-scoped resources (e.g., inspecting all nodes or creating storageclasses).
• Grants permissions to namespace-scoped resources across every namespace in the cluster (e.g., an SRE team listing pods and services cluster-wide).

Pattern 2: ClusterRole + RoleBinding (Namespace-Scoped Reuse)

• A ClusterRole is defined once globally (e.g., a standard set of developer permissions or the built-in edit role).
• A local RoleBinding created inside namespace finance references that ClusterRole in its roleRef.
• The subject receives the defined permissions strictly inside finance, with zero access in any other namespace.
• Architectural Advantage: Eliminates the operational overhead of creating and maintaining duplicate Role manifests across dozens of namespaces.

---

3. Built-in System ClusterRoles in Kubernetes

Kubernetes provides pre-configured ClusterRoles designed for standard organizational tiers:

[!IMPORTANT] Why the Built-in view Role Excludes Secrets: The built-in view ClusterRole intentionally excludes permissions to read secrets or roles/rolebindings. Because Kubernetes Secrets frequently store database passwords, API tokens, and TLS private keys, granting read-only users access to Secrets would allow immediate privilege escalation.

---

4. Non-Resource URLs in ClusterRoles

In addition to Kubernetes API resources, a ClusterRole can grant access to raw HTTP endpoints exposed by the API server (such as health check probes and Prometheus metrics scrapers):

• Common endpoints: /healthz, /livez, /readyz, /metrics, /version, /openapi/v2.
• Non-resource rules use the nonResourceURLs attribute instead of apiGroups and resources.

Non-Resource URL Manifest Example:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: prometheus-scraper
rules:
# Rule 1: Scrape metrics from API server
- nonResourceURLs: ["/metrics", "/metrics/*"]
  verbs: ["get"]
# Rule 2: Inspect cluster nodes and endpoints
- apiGroups: [""]
  resources: ["nodes", "nodes/metrics", "services", "endpoints", "pods"]
  verbs: ["get", "list", "watch"]

[!CAUTION] A single RBAC rule cannot combine resources and nonResourceURLs. They must be declared in separate rule entries within the rules array.

---

5. ClusterRole Aggregation (aggregationRule)

ClusterRole Aggregation allows Kubernetes to dynamically combine permissions from multiple fine-grained ClusterRoles into a single aggregate ClusterRole using label selectors.

+-----------------------------------------------------------------------------------------+
|                              CLUSTERROLE AGGREGATION FLOW                               |
|                                                                                         |
|   SOURCE CLUSTERROLE 1                         SOURCE CLUSTERROLE 2                     |
|   +------------------------------------+       +------------------------------------+   |
|   | Name: crd-widget-reader            |       | Name: crd-gadget-reader            |   |
|   | Label: rbac.example.com/app: read  |       | Label: rbac.example.com/app: read  |   |
|   | Rules: get/list widgets            |       | Rules: get/list gadgets            |   |
|   +-----------------+------------------+       +------------------+-----------------+   |
|                     |                                             |                     |
|                     +----------------------+----------------------+                     |
|                                            |                                            |
|                                            v                                            |
|   AGGREGATE CLUSTERROLE: custom-app-reader                                              |
|   +---------------------------------------------------------------------------------+   |
|   | aggregationRule:                                                                |   |
|   |   clusterRoleSelectors:                                                         |   |
|   |   - matchLabels:                                                                |   |
|   |       rbac.example.com/app: read                                                |   |
|   |                                                                                 |   |
|   | rules: [DYNAMICALLY POPULATED BY CONTROLLER MANAGER]                            |   |
|   | - get/list widgets                                                              |   |
|   | - get/list gadgets                                                              |   |
|   +---------------------------------------------------------------------------------+   |
+-----------------------------------------------------------------------------------------+

Aggregate ClusterRole YAML Manifest:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: aggregate-monitoring-role
aggregationRule:
  clusterRoleSelectors:
  - matchLabels:
      rbac.authorization.k8s.io/aggregate-to-monitoring: "true"
rules: [] # Automatically populated by the ClusterRoleAggregation controller

Contributing Source ClusterRole Manifest:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: custom-metrics-reader
  labels:
    rbac.authorization.k8s.io/aggregate-to-monitoring: "true"
rules:
- apiGroups: ["custom.metrics.k8s.io"]
  resources: ["*"]
  verbs: ["get", "list"]

---

6. Subresources at the Cluster Level

Cluster-level resources support distinct subresources that govern specialized administrative operations:

• nodes/proxy: Allows executing raw HTTP requests forwarded to the node kubelet.
• nodes/metrics: Allows scraping kubelet cAdvisor container metrics.
• nodes/status: Governs modifying node readiness conditions (used by node controllers).
• pods/exec, pods/portforward, pods/log: Operational subresources.

---

7. Imperative Creation Speed Commands for CKA

# 1. Create a ClusterRole for node and PV inspection
kubectl create clusterrole storage-node-viewer \
  --verb=get,list,watch \
  --resource=nodes,persistentvolumes,storageclasses

# 2. Create a ClusterRole with non-resource URLs
kubectl create clusterrole metrics-viewer \
  --verb=get \
  --non-resource-url=/metrics,/metrics/*

# 3. Create a global ClusterRoleBinding for a user
kubectl create clusterrolebinding bind-node-viewer-user \
  --clusterrole=storage-node-viewer \
  --user=auditor-sam

# 4. Create a global ClusterRoleBinding for a group
kubectl create clusterrolebinding bind-node-viewer-group \
  --clusterrole=storage-node-viewer \
  --group=sre-team

# 5. Create a global ClusterRoleBinding for a ServiceAccount
kubectl create clusterrolebinding bind-node-viewer-sa \
  --clusterrole=storage-node-viewer \
  --serviceaccount=monitoring:prometheus-sa

# 6. Scope a ClusterRole to a single namespace using a RoleBinding
kubectl create rolebinding bind-edit-to-dev \
  --clusterrole=edit \
  --user=developer-dave \
  -n development