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

# Roles

> Manage Kubernetes Roles for namespace-scoped RBAC permissions

Roles define permissions within a specific namespace. Unlike ClusterRoles, Roles can only grant access to resources within the namespace where they are created.

## Key Concepts

<CardGroup cols={2}>
  <Card title="Role" icon="shield">
    A namespace-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="Namespace" icon="box">
    The namespace where the Role exists and can grant permissions.
  </Card>

  <Card title="System Role" icon="shield-halved">
    Built-in Roles managed by Kubernetes (prefixed with `system:` or containing `kubernetes.io`).
  </Card>
</CardGroup>

<Info>
  Roles are **namespace-scoped** resources. They can only grant access to resources within the same namespace. For cluster-wide permissions, use ClusterRoles.
</Info>

## Required Permissions

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

## Role Types

| Type       | Description                                        |
| ---------- | -------------------------------------------------- |
| **System** | Built-in Kubernetes roles (should not be modified) |
| **Custom** | User-created Roles                                 |

<Warning>
  System roles (names starting with `system:` or containing `kubernetes.io`) are managed by Kubernetes and should not be modified or deleted.
</Warning>

## How to View Roles

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

  <Step title="Select Namespace">
    Choose a namespace to view Roles in that namespace.
  </Step>

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

## How to View Role Details

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

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

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

    * **Overview**: Name, namespace, type (system/custom), rules count, age
    * **Rules**: Detailed list of permissions (verbs, resources, API groups)
    * **Labels & Annotations**: Metadata attached to the Role
  </Step>
</Steps>

## How to Create a Role

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

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

    * `metadata.namespace` - Target namespace
    * `rules` - Array of permission rules
  </Step>

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

## How to Edit a Role

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

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

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

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

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

## How to Delete a Role

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

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

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

<Warning>
  Deleting a Role removes the permissions it grants within the namespace. Any subjects bound to this role via RoleBindings will lose those permissions immediately.
</Warning>

## Rule Structure

Each rule in a Role 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            |

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

### Pod Reader

```yaml theme={null}
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: pod-reader
  namespace: default
rules:
  - apiGroups: [""]
    resources: ["pods"]
    verbs: ["get", "list", "watch"]
```

### Deployment Manager

```yaml theme={null}
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: deployment-manager
  namespace: production
rules:
  - apiGroups: ["apps"]
    resources: ["deployments"]
    verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
  - apiGroups: [""]
    resources: ["pods"]
    verbs: ["get", "list", "watch"]
```

### ConfigMap and Secret Manager

```yaml theme={null}
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: config-manager
  namespace: app-namespace
rules:
  - apiGroups: [""]
    resources: ["configmaps", "secrets"]
    verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
```

### Specific Resource Access

```yaml theme={null}
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: specific-configmap-reader
  namespace: default
rules:
  - apiGroups: [""]
    resources: ["configmaps"]
    resourceNames: ["app-config", "db-config"]
    verbs: ["get"]
```

### Full Namespace Admin

```yaml theme={null}
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: namespace-admin
  namespace: development
rules:
  - apiGroups: ["*"]
    resources: ["*"]
    verbs: ["*"]
```

## Role vs ClusterRole

| Aspect         | Role                          | ClusterRole                              |
| -------------- | ----------------------------- | ---------------------------------------- |
| **Scope**      | Single namespace              | Cluster-wide                             |
| **Can access** | Namespace resources only      | All resources including cluster-scoped   |
| **Use case**   | Team/app specific permissions | Admin, operators, cross-namespace access |
| **Binding**    | RoleBinding only              | RoleBinding or ClusterRoleBinding        |

<Tip>
  Use Roles for namespace-isolated workloads. Use ClusterRoles when you need to grant the same permissions across multiple namespaces or access cluster-scoped resources.
</Tip>

## Troubleshooting

<AccordionGroup>
  <Accordion title="User cannot access namespace resources">
    * Verify a RoleBinding exists binding the user to a Role
    * Check the Role has the necessary rules
    * Verify the Role and RoleBinding are in the same namespace
    * Use `kubectl auth can-i --as=<user> -n <namespace>` to test permissions
  </Accordion>

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

  <Accordion title="Permission changes not taking effect">
    * RBAC changes are immediate, no restart needed
    * Verify the RoleBinding references the correct Role
    * Check if there are multiple Roles/bindings affecting the user
    * Clear any client-side caching
  </Accordion>

  <Accordion title="Role in wrong namespace">
    * Roles only grant permissions in their namespace
    * Delete and recreate the Role in the correct namespace
    * Or use a ClusterRole with RoleBinding for reusability
  </Accordion>

  <Accordion title="Cannot access resources in other namespaces">
    * Roles are namespace-scoped
    * Create separate Roles in each namespace, or
    * Use ClusterRole with RoleBinding per namespace, or
    * Use ClusterRole with ClusterRoleBinding for all namespaces
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="What is the difference between Role and ClusterRole?">
    **Role** is namespace-scoped and can only grant access to resources within that namespace.

    **ClusterRole** is cluster-scoped and can grant access to cluster-scoped resources (nodes, PVs), non-resource endpoints, and resources across all namespaces.
  </Accordion>

  <Accordion title="Can a Role grant access to cluster-scoped resources?">
    No. Roles can only grant access to namespace-scoped resources within their namespace. For cluster-scoped resources like nodes, PVs, or namespaces themselves, use ClusterRoles.
  </Accordion>

  <Accordion title="How do I reuse a Role across namespaces?">
    You have two options:

    1. Create identical Roles in each namespace
    2. Use a ClusterRole and bind it with RoleBindings in each namespace (recommended)

    The second approach is easier to maintain.
  </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 the recommended way to reuse permission sets across namespaces.
  </Accordion>

  <Accordion title="What happens if I delete a namespace with Roles?">
    When a namespace is deleted, all Roles and RoleBindings in that namespace are automatically deleted. This is part of Kubernetes garbage collection.
  </Accordion>

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

  <Accordion title="Can a Role grant permissions to resources it doesn't have?">
    No. You cannot escalate privileges. A user can only create Roles with permissions they already have. This prevents privilege escalation attacks.
  </Accordion>

  <Accordion title="Should I create Roles or use built-in ClusterRoles?">
    Use built-in ClusterRoles (`admin`, `edit`, `view`) with RoleBindings for common scenarios. Create custom Roles when you need fine-grained, namespace-specific permissions that don't match built-in roles.
  </Accordion>
</AccordionGroup>