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

> Manage Kubernetes ClusterRoles for cluster-wide RBAC permissions

ClusterRoles define permissions that apply across the entire cluster. Unlike namespace-scoped Roles, ClusterRoles can grant access to cluster-scoped resources (nodes, PVs), non-resource endpoints, and resources across all namespaces.

## Key Concepts

<CardGroup cols={2}>
  <Card title="ClusterRole" icon="shield">
    A cluster-scoped set of permissions defined as rules with verbs, resources, and API groups.
  </Card>

  <Card title="Rules" icon="key">
    Permission definitions specifying what actions (verbs) are allowed on which resources.
  </Card>

  <Card title="System Role" icon="shield-halved">
    Built-in ClusterRoles managed by Kubernetes (prefixed with `system:`, `admin`, `edit`, `view`).
  </Card>

  <Card title="Aggregation" icon="layers">
    ClusterRoles that automatically combine rules from other ClusterRoles via label selectors.
  </Card>
</CardGroup>

<Info>
  ClusterRoles are **cluster-scoped** resources. They define permissions that can be granted across all namespaces or to cluster-level resources via ClusterRoleBindings.
</Info>

## Required Permissions

| Action             | Permission                                     |
| ------------------ | ---------------------------------------------- |
| View ClusterRoles  | `iam:project:infrastructure:kubernetes:read`   |
| Create ClusterRole | `iam:project:infrastructure:kubernetes:write`  |
| Edit ClusterRole   | `iam:project:infrastructure:kubernetes:write`  |
| Delete ClusterRole | `iam:project:infrastructure:kubernetes:delete` |

## Role Types

| Type           | Description                                             |
| -------------- | ------------------------------------------------------- |
| **System**     | Built-in Kubernetes roles (cannot be deleted)           |
| **Custom**     | User-created ClusterRoles                               |
| **Aggregated** | ClusterRoles that combine rules from other ClusterRoles |

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

## How to View ClusterRoles

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

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

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

## How to View ClusterRole Details

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

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

  <Step title="Review Details">
    View ClusterRole information including:

    * **Overview**: Name, type (system/custom), rules count, age
    * **Rules**: Detailed list of permissions (verbs, resources, API groups)
    * **Aggregation Rule**: Label selectors for aggregated roles
    * **Labels & Annotations**: Metadata attached to the ClusterRole
  </Step>
</Steps>

## How to Create a ClusterRole

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

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

    * `rules` - Array of permission rules
    * `aggregationRule` - Optional, for aggregated roles
  </Step>

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

## How to Edit a ClusterRole

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

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

  <Step title="Modify Rules">
    Edit the ClusterRole rules. Add, remove, or modify permissions as needed.
  </Step>

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

<Warning>
  Modifying system ClusterRoles can break cluster functionality. Only edit custom ClusterRoles unless you understand the implications.
</Warning>

## How to Delete a ClusterRole

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

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

  <Step title="Confirm">
    Confirm the deletion. Any ClusterRoleBindings referencing this role will be affected.
  </Step>
</Steps>

<Warning>
  Deleting a ClusterRole removes the permissions it grants. Any subjects bound to this role via ClusterRoleBindings will lose those permissions immediately.
</Warning>

## Rule Structure

Each rule in a ClusterRole specifies:

| Field               | Description                                                     |
| ------------------- | --------------------------------------------------------------- |
| **apiGroups**       | API groups containing the resources (empty string for core API) |
| **resources**       | Resource types to grant access to                               |
| **verbs**           | Actions allowed on the resources                                |
| **resourceNames**   | Optional: specific resource names to restrict access            |
| **nonResourceURLs** | Optional: non-resource URLs (e.g., `/healthz`)                  |

### Common Verbs

| Verb               | Description                |
| ------------------ | -------------------------- |
| `get`              | Read a single resource     |
| `list`             | List resources             |
| `watch`            | Watch for changes          |
| `create`           | Create new resources       |
| `update`           | Update existing resources  |
| `patch`            | Partially update resources |
| `delete`           | Delete resources           |
| `deletecollection` | Delete multiple resources  |
| `*`                | All verbs (full access)    |

## Example ClusterRoles

### Read-Only Cluster Access

```yaml theme={null}
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: cluster-reader
rules:
  - apiGroups: [""]
    resources: ["*"]
    verbs: ["get", "list", "watch"]
  - apiGroups: ["apps", "batch"]
    resources: ["*"]
    verbs: ["get", "list", "watch"]
```

### Node Administrator

```yaml theme={null}
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: node-admin
rules:
  - apiGroups: [""]
    resources: ["nodes"]
    verbs: ["get", "list", "watch", "update", "patch"]
  - apiGroups: [""]
    resources: ["nodes/status"]
    verbs: ["get", "update", "patch"]
```

### PV Manager

```yaml theme={null}
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: pv-manager
rules:
  - apiGroups: [""]
    resources: ["persistentvolumes"]
    verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
  - apiGroups: ["storage.k8s.io"]
    resources: ["storageclasses"]
    verbs: ["get", "list", "watch"]
```

### Aggregated ClusterRole

```yaml theme={null}
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: monitoring-endpoints
  labels:
    rbac.example.com/aggregate-to-monitoring: "true"
rules:
  - apiGroups: [""]
    resources: ["services", "endpoints", "pods"]
    verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: monitoring
aggregationRule:
  clusterRoleSelectors:
    - matchLabels:
        rbac.example.com/aggregate-to-monitoring: "true"
rules: []  # Rules are automatically filled by aggregation
```

## Built-in ClusterRoles

| Role                               | Description                                              |
| ---------------------------------- | -------------------------------------------------------- |
| **cluster-admin**                  | Full access to all resources in all namespaces           |
| **admin**                          | Full access within a namespace (when bound to namespace) |
| **edit**                           | Read/write access to most resources in a namespace       |
| **view**                           | Read-only access to most resources in a namespace        |
| **system:node**                    | Permissions for kubelets                                 |
| **system:kube-scheduler**          | Permissions for the scheduler                            |
| **system:kube-controller-manager** | Permissions for controller manager                       |

<Tip>
  Use the built-in `admin`, `edit`, and `view` roles as templates for custom roles, or bind them directly for common use cases.
</Tip>

## Troubleshooting

<AccordionGroup>
  <Accordion title="User cannot access cluster resources">
    * Verify a ClusterRoleBinding exists binding the user to a ClusterRole
    * Check the ClusterRole has the necessary rules
    * Use `kubectl auth can-i` to test permissions
    * Verify the subject (user/group/serviceaccount) is correct
  </Accordion>

  <Accordion title="Cannot delete ClusterRole">
    * System roles cannot be deleted (names starting with `system:`, `admin`, `edit`, `view`)
    * Verify you have delete permission
    * Check for finalizers blocking deletion
  </Accordion>

  <Accordion title="Aggregated ClusterRole not updating">
    * Verify source ClusterRoles have matching labels
    * Check aggregationRule selector syntax
    * Label changes may take a moment to propagate
    * Verify source ClusterRoles exist
  </Accordion>

  <Accordion title="Permission changes not taking effect">
    * RBAC changes are immediate, no restart needed
    * Clear any client-side caching (kubectl, dashboard)
    * Verify the binding is correct (ClusterRoleBinding vs RoleBinding)
    * Check for conflicting roles that might override permissions
  </Accordion>

  <Accordion title="Wildcard permissions not working as expected">
    * `*` in verbs grants all verbs
    * `*` in resources grants access to all resources in specified apiGroups
    * Empty apiGroups `[""]` means core API only
    * Use `["*"]` for all API groups
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="What is the difference between ClusterRole and Role?">
    **ClusterRole** is cluster-scoped and can:

    * Grant access to cluster-scoped resources (nodes, PVs, namespaces)
    * Grant access across all namespaces
    * Grant access to non-resource endpoints

    **Role** is namespace-scoped and only grants access within a single namespace.
  </Accordion>

  <Accordion title="How do I grant cluster-admin access?">
    Create a ClusterRoleBinding that binds the user/group to the built-in `cluster-admin` ClusterRole. Be very careful - this grants full access to everything.
  </Accordion>

  <Accordion title="What are aggregated ClusterRoles?">
    Aggregated ClusterRoles automatically combine rules from other ClusterRoles that match specific labels. This allows extending permissions without modifying the original role. The `admin`, `edit`, and `view` roles use aggregation.
  </Accordion>

  <Accordion title="Can I use ClusterRoles with RoleBindings?">
    Yes. A RoleBinding can reference a ClusterRole, but the permissions are limited to the RoleBinding's namespace. This is useful for reusing common permission sets across namespaces.
  </Accordion>

  <Accordion title="How do I check what permissions a ClusterRole grants?">
    View the ClusterRole details to see all rules. Use `kubectl describe clusterrole <name>` or click on the ClusterRole in the UI to see the complete rule list.
  </Accordion>

  <Accordion title="What is the principle of least privilege?">
    Grant only the minimum permissions needed. Instead of `cluster-admin`, create custom ClusterRoles with specific verbs and resources. Use `get`, `list`, `watch` for read-only access instead of `*`.
  </Accordion>

  <Accordion title="How do non-resource URLs work?">
    Non-resource URLs like `/healthz`, `/api`, `/metrics` are accessed via `nonResourceURLs` in rules instead of `resources`. They require explicit rules since they're not Kubernetes resources.
  </Accordion>

  <Accordion title="Can I restrict a ClusterRole to specific namespaces?">
    No. ClusterRoles define permissions, not where they apply. Use RoleBindings (with a ClusterRole reference) to limit permissions to specific namespaces, or use ClusterRoleBindings for cluster-wide access.
  </Accordion>
</AccordionGroup>