Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.shiftlabs.dev/llms.txt

Use this file to discover all available pages before exploring further.

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

ActionPermission
View ClusterRoleBindingsiam:project:infrastructure:kubernetes:read
Create ClusterRoleBindingiam:project:infrastructure:kubernetes:write
Edit ClusterRoleBindingiam:project:infrastructure:kubernetes:write
Delete ClusterRoleBindingiam:project:infrastructure:kubernetes:delete

​
Binding Types

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

​
Subject Types

TypeDescription
UserA human user authenticated to the cluster
GroupA collection of users (e.g., system:masters)
ServiceAccountA Kubernetes service account for pods

​
How to View ClusterRoleBindings

1

Select Cluster

Choose a cluster from the cluster dropdown.
2

View List

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

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

1

Find the ClusterRoleBinding

Locate the ClusterRoleBinding in the list.
2

Click Binding Name

Click on the binding name to open the detail drawer.
3

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

1

Click Create Binding

Click the Create Binding button in the page header.
2

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
3

Create

Click Create to apply the manifest.

​
How to Edit a ClusterRoleBinding

1

Open Actions Menu

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

Click Edit YAML

Select Edit YAML to open the YAML editor.
3

Modify Subjects

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

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

1

Open Actions Menu

Click the actions menu on the binding row.
2

Click Delete

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

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

FieldDescription
kindType of subject: User, Group, or ServiceAccount
nameName of the user, group, or service account
namespaceRequired for ServiceAccounts, empty for Users/Groups
apiGrouprbac.authorization.k8s.io for Users/Groups, empty for ServiceAccounts

​
Common System Bindings

BindingRoleDescription
cluster-admincluster-adminSuper-user access (system:masters group)
system:nodesystem:nodePermissions for kubelets
system:kube-schedulersystem:kube-schedulerScheduler permissions
system:kube-controller-managersystem:kube-controller-managerController manager permissions

​
Troubleshooting

  • 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
  • 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)
  • System bindings cannot be deleted
  • Verify you have delete permission
  • Check for finalizers blocking deletion
  • RBAC changes are immediate
  • Clear any client-side caching
  • Verify the binding was actually updated
  • Check if there are conflicting bindings
  • roleRef is immutable after creation
  • Delete the binding and create a new one
  • This is by design to prevent privilege escalation

​
FAQ

ClusterRoleBinding grants permissions cluster-wide across all namespaces.RoleBinding grants permissions only within a single namespace, even if it references a ClusterRole.
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.
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.
Create a ClusterRoleBinding that binds the user to the cluster-admin ClusterRole. Be cautious - this grants full access to everything in the cluster.
Yes. You can have multiple ClusterRoleBindings referencing the same ClusterRole, each with different subjects. Permissions are additive.
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).
The user immediately loses the permissions granted by that binding. If they have other bindings, those permissions remain. RBAC changes take effect instantly.
Yes. ServiceAccounts can be subjects in ClusterRoleBindings, granting them cluster-wide permissions. Always specify the namespace where the ServiceAccount exists.