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

# Role Bindings

> Manage Kubernetes RoleBindings to grant namespace-scoped permissions to users, groups, and service accounts

RoleBindings grant the permissions defined in a Role or ClusterRole to subjects (users, groups, or service accounts) within a specific namespace. They connect Roles to identities that need those permissions.

## Key Concepts

<CardGroup cols={2}>
  <Card title="RoleBinding" icon="link">
    A namespace-scoped binding that grants Role or ClusterRole permissions to subjects within a namespace.
  </Card>

  <Card title="Role Reference" icon="shield">
    The Role or 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:` or `kubeadm:`).
  </Card>
</CardGroup>

<Info>
  RoleBindings are **namespace-scoped** resources. They can reference either a Role (same namespace) or a ClusterRole, but permissions are always limited to the RoleBinding's namespace.
</Info>

## Required Permissions

| Action             | Permission                                     |
| ------------------ | ---------------------------------------------- |
| View RoleBindings  | `iam:project:infrastructure:kubernetes:read`   |
| Create RoleBinding | `iam:project:infrastructure:kubernetes:write`  |
| Edit RoleBinding   | `iam:project:infrastructure:kubernetes:write`  |
| Delete RoleBinding | `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:` or `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:authenticated`) |
| **ServiceAccount** | A Kubernetes service account for pods                |

## How to View RoleBindings

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

  <Step title="Select Namespace">
    Choose a namespace to view RoleBindings in that namespace.
  </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 RoleBinding Details

<Steps>
  <Step title="Find the RoleBinding">
    Locate the RoleBinding 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, namespace, type (system/custom), age
    * **Role Reference**: The Role or ClusterRole being bound (kind and name)
    * **Subjects**: List of users, groups, and service accounts
    * **Labels & Annotations**: Metadata attached to the binding
  </Step>
</Steps>

## How to Create a RoleBinding

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

  <Step title="Write YAML">
    Enter the RoleBinding manifest in YAML format. Key fields:

    * `metadata.namespace` - Target namespace
    * `roleRef` - Reference to the Role or 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 RoleBinding

<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 RoleBinding.
</Warning>

## How to Delete a RoleBinding

<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 within the namespace.
  </Step>
</Steps>

<Warning>
  Deleting a RoleBinding immediately revokes permissions from all subjects within that namespace. They will lose access to resources granted by the bound Role or ClusterRole.
</Warning>

## Example RoleBindings

### Bind Role to User

```yaml theme={null}
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: developer-pods
  namespace: development
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: pod-reader
subjects:
  - kind: User
    name: developer@example.com
    apiGroup: rbac.authorization.k8s.io
```

### Bind ClusterRole to Namespace

```yaml theme={null}
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: admin-binding
  namespace: production
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: admin
subjects:
  - kind: User
    name: admin@example.com
    apiGroup: rbac.authorization.k8s.io
```

### Grant Permissions to ServiceAccount

```yaml theme={null}
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: app-config-reader
  namespace: app-namespace
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: configmap-reader
subjects:
  - kind: ServiceAccount
    name: app-service-account
    namespace: app-namespace
```

### Multiple Subjects

```yaml theme={null}
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: team-binding
  namespace: team-namespace
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: edit
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: dev-team
    apiGroup: rbac.authorization.k8s.io
  - kind: ServiceAccount
    name: ci-runner
    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 |

## RoleBinding vs ClusterRoleBinding

| Aspect                   | RoleBinding                      | ClusterRoleBinding  |
| ------------------------ | -------------------------------- | ------------------- |
| **Scope**                | Single namespace                 | Cluster-wide        |
| **Can reference**        | Role or ClusterRole              | ClusterRole only    |
| **Permissions apply to** | Resources in binding's namespace | All namespaces      |
| **Use case**             | Team/app specific access         | Cluster-wide access |

<Tip>
  Use RoleBindings with ClusterRoles to reuse permission sets across namespaces without granting cluster-wide access. The permissions are limited to the RoleBinding's namespace.
</Tip>

## Troubleshooting

<AccordionGroup>
  <Accordion title="User cannot access namespace resources">
    * Verify a RoleBinding exists in the correct namespace
    * Check the subject name matches exactly (case-sensitive)
    * Verify the referenced Role or ClusterRole has the needed permissions
    * Use `kubectl auth can-i --as=<user> -n <namespace>` 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 RoleBinding is in the same namespace as the pod
  </Accordion>

  <Accordion title="Cannot delete RoleBinding">
    * 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>

  <Accordion title="ClusterRole permissions not working in namespace">
    * Verify the RoleBinding references the ClusterRole correctly
    * Check the RoleBinding is in the target namespace
    * Ensure the ClusterRole has the necessary rules
    * ClusterRole permissions are limited to the RoleBinding's namespace
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="What is the difference between RoleBinding and ClusterRoleBinding?">
    **RoleBinding** grants permissions only within a single namespace. It can reference either a Role or ClusterRole.

    **ClusterRoleBinding** grants permissions cluster-wide across all namespaces and can only reference ClusterRoles.
  </Accordion>

  <Accordion title="Can a RoleBinding reference 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.
  </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 the same permissions in multiple namespaces?">
    You have two options:

    1. Create separate RoleBindings in each namespace referencing the same Role (requires Role in each namespace)
    2. Create a ClusterRole and bind it with RoleBindings in each namespace (recommended)

    The second approach is easier to maintain since you only update the ClusterRole.
  </Accordion>

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

  <Accordion title="What happens when I delete a user's binding?">
    The user immediately loses the permissions granted by that binding in that namespace. If they have other bindings (in this or other namespaces), those permissions remain. RBAC changes take effect instantly.
  </Accordion>

  <Accordion title="Can a ServiceAccount from another namespace be a subject?">
    Yes. You can grant permissions to a ServiceAccount from any namespace. Specify both the name and namespace in the subject. The ServiceAccount will have permissions in the RoleBinding's namespace.
  </Accordion>

  <Accordion title="What happens if the referenced Role doesn't exist?">
    The RoleBinding is created but grants no permissions. Subjects will not have access to any resources until the referenced Role is created. Kubernetes does not validate that the roleRef exists.
  </Accordion>
</AccordionGroup>