ClusterRole and ClusterRoleBinding

Namespaced Roles can't grant access to cluster-scoped resources (nodes, PVs, namespaces, CSRs) or apply across all namespaces at once. Cluster-wide permissions need a cluster-scoped RBAC mechanism.

Solution: Use a ClusterRole + ClusterRoleBinding for cluster-scoped resources (nodes, PVs) or to grant the same permissions across all namespaces.

Now hand a senior engineer a master keycard that opens doors in every building across the whole port, not just one. The same card also reaches shared facilities that belong to no single building at all, the main gates, the rail yard, the perimeter fence. In Kubernetes a ClusterRole is that port-wide list of doors, a ClusterRoleBinding is the master card linking it to a person, and together they grant access across all namespaces plus cluster-scoped resources like nodes that no namespace owns.

The same cluster entities appear in every day's notes; the diagram below shows where this day's topic fits.

Role/RoleBinding (Day 23) are namespaced — they can't grant access to:

   - cluster-scoped resources: nodes, persistentvolumes, namespaces, CSRs
   - resources across ALL namespaces at once

ClusterRole + ClusterRoleBinding solve exactly that.

RBAC has two tiers: namespaced objects (Role + RoleBinding) and cluster-wide objects (ClusterRole + ClusterRoleBinding). The binding decides the scope.

   SCOPE        PERMISSIONS        BINDING
   namespace    Role               RoleBinding         -> one namespace
   cluster      ClusterRole        ClusterRoleBinding  -> whole cluster

Concretely, that means each permission object can reach a different set of resources:

   Role         -> verbs on namespaced resources, in ONE namespace
   ClusterRole  -> verbs on cluster-scoped resources, OR namespaced
                   resources across EVERY namespace

Trick: a ClusterRole can be reused by a RoleBinding to grant it in just one namespace — write the permission once, scope it where you like.

Ask the API which resources live outside namespaces — those are the ones that require a ClusterRole to grant access.

kubectl api-resources --namespaced=false    # cluster-scoped (nodes, pv, ns...)
kubectl api-resources --namespaced=true     # namespaced (pods, svc, cm...)

A ClusterRole defines a set of verbs on resources, just like a Role, but it is not tied to any namespace. This is the real Prometheus ClusterRole: the monitoring server must read nodes, services, endpoints, and pods across every namespace to discover its scrape targets.

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: prometheus
rules:
  - apiGroups: [""]
    resources: ["nodes", "nodes/metrics", "services", "endpoints", "pods"]
    verbs: ["get", "list", "watch"]
  - nonResourceURLs: ["/metrics"]      # scrape the api-server's own metrics
    verbs: ["get"]

A ClusterRoleBinding attaches a ClusterRole to a subject across the entire cluster, every namespace included. Prometheus runs as a ServiceAccount, so the binding targets that SA.

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: prometheus
subjects:
  - kind: ServiceAccount
    name: prometheus
    namespace: monitoring
roleRef:
  kind: ClusterRole
  name: prometheus
  apiGroup: rbac.authorization.k8s.io

The same objects can be created in one line with kubectl create, handy in the exam and for quick experiments.

kubectl create clusterrole prometheus \
  --verb=get,list,watch --resource=nodes,services,endpoints,pods

kubectl create clusterrolebinding prometheus \
  --clusterrole=prometheus --serviceaccount=monitoring:prometheus

Use kubectl auth can-i with --as to confirm the binding actually grants the access you intended.

kubectl auth can-i list nodes \
  --as=system:serviceaccount:monitoring:prometheus     # -> yes (cluster-wide)
kubectl auth can-i list pods -A \
  --as=system:serviceaccount:monitoring:prometheus     # -> yes (every namespace)

Kubernetes ships with default ClusterRoles you can bind directly instead of writing your own.

   cluster-admin -> god mode (all verbs, all resources) — handle with care
   admin / edit  -> common namespace-level roles (used via RoleBinding)
   view          -> read-only

Prometheus needs to read nodes (cluster-scoped) and pods/services in every namespace, which only a ClusterRole can grant.

Graph legend — each step maps to a concrete object or decision:

Cluster-scoped resources like nodes can only be granted through a ClusterRole.

Graph legend — each node maps to a concrete object or decision:

• ClusterRole/ClusterRoleBinding = cluster-wide RBAC.
• Needed for cluster-scoped resources (nodes, PVs, namespaces, CSRs) and for granting access across all namespaces.
• A ClusterRole can be bound by a RoleBinding to limit it to one namespace.
• Use kubectl api-resources --namespaced=false to see what's cluster-scoped.

• [ ] Listed cluster-scoped resources with api-resources --namespaced=false
• [ ] Created the prometheus ClusterRole + ClusterRoleBinding
• [ ] Verified kubectl auth can-i list nodes --as=system:serviceaccount:monitoring:prometheus
• [ ] Understand reusing a ClusterRole via a RoleBinding for one namespace