Cluster Role Bindings

ClusterRoleBindings grant the permissions defined in a ClusterRole to subjects (users, groups, or service accounts) across the entire cluster. They are the mechanism that connects ClusterRoles to the identities that need those permissions.

Key Concepts

ClusterRoleBinding

A cluster-scoped binding that grants ClusterRole permissions to subjects across all namespaces.

Role Reference

The ClusterRole whose permissions are being granted by this binding.

Subjects

The users, groups, or service accounts receiving the permissions.

System Binding

Built-in bindings managed by Kubernetes (prefixed with system:, cluster-admin, kubeadm:).

ClusterRoleBindings are cluster-scoped resources. They grant permissions across all namespaces, unlike RoleBindings which are namespace-scoped.

Required Permissions

Action	Permission
View ClusterRoleBindings	`iam:project:infrastructure:kubernetes:read`
Create ClusterRoleBinding	`iam:project:infrastructure:kubernetes:write`
Edit ClusterRoleBinding	`iam:project:infrastructure:kubernetes:write`
Delete ClusterRoleBinding	`iam:project:infrastructure:kubernetes:delete`

Binding Types

Type	Description
System	Built-in Kubernetes bindings (cannot be deleted)
Custom	User-created bindings

System bindings (names starting with system:, cluster-admin, kubeadm:) are managed by Kubernetes and should not be modified or deleted.

Subject Types

Type	Description
User	A human user authenticated to the cluster
Group	A collection of users (e.g., `system:masters`)
ServiceAccount	A Kubernetes service account for pods

How to View ClusterRoleBindings

Select Cluster

Choose a cluster from the cluster dropdown.

View List

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

Filter and Search

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

How to View ClusterRoleBinding Details

Find the ClusterRoleBinding

Locate the ClusterRoleBinding in the list.

Click Binding Name

Click on the binding name to open the detail drawer.

Review Details

View binding information including:

Overview: Name, type (system/custom), age
Role Reference: The ClusterRole being bound
Subjects: List of users, groups, and service accounts
Labels & Annotations: Metadata attached to the binding

How to Create a ClusterRoleBinding

Click Create Binding

Click the Create Binding button in the page header.

Write YAML

Enter the ClusterRoleBinding manifest in YAML format. Key fields:

roleRef - Reference to the ClusterRole to bind
subjects - List of users, groups, or service accounts

Create

Click Create to apply the manifest.

How to Edit a ClusterRoleBinding

Open Actions Menu

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

Click Edit YAML

Select Edit YAML to open the YAML editor.

Modify Subjects

Edit the binding. You can add or remove subjects, but the roleRef is immutable.

Save

Click Update to apply changes.

The roleRef field is immutable after creation. To change the referenced role, delete and recreate the ClusterRoleBinding.

How to Delete a ClusterRoleBinding

Open Actions Menu

Click the actions menu on the binding row.

Click Delete

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

Confirm

Confirm the deletion. Subjects will immediately lose the permissions granted by this binding.

Deleting a ClusterRoleBinding immediately revokes permissions from all subjects. They will lose access to resources granted by the bound ClusterRole.

Example ClusterRoleBindings

Grant Cluster Admin to User

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: admin-user-binding
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: cluster-admin
subjects:
  - kind: User
    name: admin@example.com
    apiGroup: rbac.authorization.k8s.io

Grant Read Access to Group

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: developers-view
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: view
subjects:
  - kind: Group
    name: developers
    apiGroup: rbac.authorization.k8s.io

Grant Permissions to ServiceAccount

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

Multiple Subjects

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: ops-team-binding
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: admin
subjects:
  - kind: User
    name: alice@example.com
    apiGroup: rbac.authorization.k8s.io
  - kind: User
    name: bob@example.com
    apiGroup: rbac.authorization.k8s.io
  - kind: Group
    name: ops-team
    apiGroup: rbac.authorization.k8s.io
  - kind: ServiceAccount
    name: deploy-bot
    namespace: ci-cd

Subject Reference Format

Field	Description
kind	Type of subject: `User`, `Group`, or `ServiceAccount`
name	Name of the user, group, or service account
namespace	Required for ServiceAccounts, empty for Users/Groups
apiGroup	`rbac.authorization.k8s.io` for Users/Groups, empty for ServiceAccounts

Common System Bindings

Binding	Role	Description
cluster-admin	cluster-admin	Super-user access (system:masters group)
system:node	system:node	Permissions for kubelets
system:kube-scheduler	system:kube-scheduler	Scheduler permissions
system:kube-controller-manager	system:kube-controller-manager	Controller manager permissions

Troubleshooting

User cannot access resources

Verify a ClusterRoleBinding exists for the user
Check the subject name matches exactly (case-sensitive)
Verify the ClusterRole has the needed permissions
Use kubectl auth can-i --as=<user> to test permissions
Check for typos in user/group names

ServiceAccount permissions not working

Verify the namespace is specified in the subject
Check the ServiceAccount exists in that namespace
Ensure pods are using the correct ServiceAccount
Verify the ClusterRoleBinding is cluster-scoped (not RoleBinding)

Cannot delete ClusterRoleBinding

System bindings cannot be deleted
Verify you have delete permission
Check for finalizers blocking deletion

Changes not taking effect

RBAC changes are immediate
Clear any client-side caching
Verify the binding was actually updated
Check if there are conflicting bindings

Cannot change roleRef

roleRef is immutable after creation
Delete the binding and create a new one
This is by design to prevent privilege escalation

FAQ

What is the difference between ClusterRoleBinding and RoleBinding?

ClusterRoleBinding grants permissions cluster-wide across all namespaces.RoleBinding grants permissions only within a single namespace, even if it references a ClusterRole.

Can I bind a ClusterRole with a RoleBinding?

Yes. A RoleBinding can reference a ClusterRole, but permissions are limited to the RoleBinding’s namespace. This is useful for reusing common roles across namespaces without granting cluster-wide access.

Why can't I change the roleRef?

The roleRef is immutable to prevent privilege escalation. If you could change it, you could escalate permissions without delete access. To change the role, delete and recreate the binding.

How do I grant admin access to a user?

Create a ClusterRoleBinding that binds the user to the cluster-admin ClusterRole. Be cautious - this grants full access to everything in the cluster.

Can multiple bindings reference the same role?

Yes. You can have multiple ClusterRoleBindings referencing the same ClusterRole, each with different subjects. Permissions are additive.

How do groups work in Kubernetes RBAC?

Groups are provided by your authentication system (OIDC, certificates, etc.). Kubernetes doesn’t manage groups - it trusts the authenticator. Common groups include system:masters (cluster-admin) and system:authenticated (all authenticated users).

What happens when I delete a user's binding?

The user immediately loses the permissions granted by that binding. If they have other bindings, those permissions remain. RBAC changes take effect instantly.

Can a ServiceAccount be in a ClusterRoleBinding?

Yes. ServiceAccounts can be subjects in ClusterRoleBindings, granting them cluster-wide permissions. Always specify the namespace where the ServiceAccount exists.

​Key Concepts