> ## 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.

# Cluster Role Bindings

> Manage Kubernetes ClusterRoleBindings to grant cluster-wide permissions to users, groups, and service accounts

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

<CardGroup cols={2}>
  <Card title="ClusterRoleBinding" icon="link">
    A cluster-scoped binding that grants ClusterRole permissions to subjects across all namespaces.
  </Card>

  <Card title="Role Reference" icon="shield">
    The ClusterRole whose permissions are being granted by this binding.
  </Card>

  <Card title="Subjects" icon="users">
    The users, groups, or service accounts receiving the permissions.
  </Card>

  <Card title="System Binding" icon="shield-halved">
    Built-in bindings managed by Kubernetes (prefixed with `system:`, `cluster-admin`, `kubeadm:`).
  </Card>
</CardGroup>

<Info>
  ClusterRoleBindings are **cluster-scoped** resources. They grant permissions across all namespaces, unlike RoleBindings which are namespace-scoped.
</Info>

## 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                            |

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

## 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

<Steps>
  <Step title="Select Cluster">
    Choose a cluster from the cluster dropdown.
  </Step>

  <Step title="View List">
    The list shows all ClusterRoleBindings in the cluster (cluster-scoped, no namespace filter).
  </Step>

  <Step title="Filter and Search">
    Use the search box to find bindings by name or role name. Filter by binding type (System, Custom).
  </Step>
</Steps>

## How to View ClusterRoleBinding Details

<Steps>
  <Step title="Find the ClusterRoleBinding">
    Locate the ClusterRoleBinding in the list.
  </Step>

  <Step title="Click Binding Name">
    Click on the binding name to open the detail drawer.
  </Step>

  <Step title="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
  </Step>
</Steps>

## How to Create a ClusterRoleBinding

<Steps>
  <Step title="Click Create Binding">
    Click the **Create Binding** button in the page header.
  </Step>

  <Step title="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
  </Step>

  <Step title="Create">
    Click **Create** to apply the manifest.
  </Step>
</Steps>

## How to Edit a ClusterRoleBinding

<Steps>
  <Step title="Open Actions Menu">
    Click the actions menu (three dots) on the binding row.
  </Step>

  <Step title="Click Edit YAML">
    Select **Edit YAML** to open the YAML editor.
  </Step>

  <Step title="Modify Subjects">
    Edit the binding. You can add or remove subjects, but the roleRef is immutable.
  </Step>

  <Step title="Save">
    Click **Update** to apply changes.
  </Step>
</Steps>

<Warning>
  The `roleRef` field is **immutable** after creation. To change the referenced role, delete and recreate the ClusterRoleBinding.
</Warning>

## How to Delete a ClusterRoleBinding

<Steps>
  <Step title="Open Actions Menu">
    Click the actions menu on the binding row.
  </Step>

  <Step title="Click Delete">
    Select **Delete** from the menu (disabled for system bindings).
  </Step>

  <Step title="Confirm">
    Confirm the deletion. Subjects will immediately lose the permissions granted by this binding.
  </Step>
</Steps>

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

## Example ClusterRoleBindings

### Grant Cluster Admin to User

```yaml theme={null}
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

```yaml theme={null}
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

```yaml theme={null}
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

```yaml theme={null}
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

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="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)
  </Accordion>

  <Accordion title="Cannot delete ClusterRoleBinding">
    * System bindings cannot be deleted
    * Verify you have delete permission
    * Check for finalizers blocking deletion
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="Cannot change roleRef">
    * roleRef is immutable after creation
    * Delete the binding and create a new one
    * This is by design to prevent privilege escalation
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Can multiple bindings reference the same role?">
    Yes. You can have multiple ClusterRoleBindings referencing the same ClusterRole, each with different subjects. Permissions are additive.
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>