ClusterRoles and ClusterRoleBindings

A monitoring agent needs to list Pods across all namespaces. A Role would not work: Roles are namespaced, so a Role in monitoring can only grant access to resources in monitoring. To read Pods everywhere, you need a ClusterRole.

Start by examining what Kubernetes ships with. In your simulated cluster:

kubectl get clusterroles | grep -v system

You will see a short list of built-in ClusterRoles that Kubernetes creates automatically. Inspect one of them:

kubectl describe clusterrole view

The view ClusterRole grants read-only access to most resources across any namespace. edit adds write access. admin adds the ability to manage RBAC objects within a namespace. cluster-admin grants unrestricted access to everything in the cluster.

ClusterRole vs Role

A ClusterRole is not tied to any namespace. Its rules can apply to resources in every namespace, and they can also apply to resources that have no namespace at all: Nodes, PersistentVolumes, StorageClasses, and Namespaces themselves are cluster-scoped and can only be granted through a ClusterRole.

The shape of a ClusterRole manifest is nearly identical to a Role. The namespace field is absent, and the kind is ClusterRole:

nano monitor-clusterrole.yaml

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: pod-lister
rules:
  - apiGroups: [""]
    resources: ["pods"]
    verbs: ["get", "list", "watch"]

kubectl apply -f monitor-clusterrole.yaml

kubectl get clusterroles | grep pod-lister

ClusterRoleBinding

A ClusterRoleBinding binds a ClusterRole to a subject with cluster-wide scope. The subject receives the ClusterRole’s permissions in every namespace, plus any cluster-scoped resources.

nano monitor-crb.yaml

Note that subjects still requires a namespace for ServiceAccount entries, because a ServiceAccount is a namespaced object even if the binding is cluster-wide:

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

kubectl apply -f monitor-crb.yaml

kubectl get clusterrolebindings | grep monitoring

The ServiceAccount monitoring-agent in the monitoring namespace can now get, list, and watch Pods in any namespace in the cluster.

A powerful pattern: ClusterRole bound with a RoleBinding

A ClusterRole can also be referenced by a regular namespaced RoleBinding. When you do this, the ClusterRole’s rules apply, but only within the namespace of that RoleBinding. This pattern lets you define permission templates once as ClusterRoles and reuse them across multiple namespaces without duplicating Role objects in every namespace.

Why does Kubernetes support this? Because maintaining identical Roles across twenty namespaces is error-prone. A single ClusterRole template with per-namespace RoleBindings is the standard pattern for shared permission sets.

ClusterRoles and ClusterRoleBindings give you the cluster-wide reach that namespaced Roles cannot provide. The next lesson shows you how to verify that these permissions actually work the way you expect, using kubectl auth can-i to test access before deploying.