> ## Documentation Index
> Fetch the complete documentation index at: https://docs.macstadium.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Role-Based Access Control (RBAC)

> Manage Orka RBAC: roles, rolebindings, and subjects. Control which users and service accounts can access which namespaces and resources.

**Admin only:** All `orka rbac` and `orka rolebinding` operations require administrative privileges.

## Understanding RBAC in Orka

Orka relies on RBAC (role-based access control) for the management of user access to resources. In Orka, RBAC consists of the following elements:

* **Roles:** A set of permissions. Roles are managed by MacStadium.
* **Subjects:** Users and service accounts which can be bound to a role. Subjects are managed by Orka users with administrative privileges.
* **Namespaces:** Groups of resources dedicated to specific users or service accounts. Namespaces are managed by Orka users with administrative privileges.
* **Rolebindings:** K8s objects describing which subjects belong to which role and which subjects can access which namespaces. Rolebindings are managed by Orka users with administrative privileges.

**Default access:**

* All admin users have access to all namespaces
* All non-admin users have user access to the `orka-default` namespace

**Granting access:**

* To grant a user access to a specific namespace, add that user as a subject to the rolebinding for the namespace
* Service accounts automatically have access to the namespace where they were created
* To grant a service account access to a specific namespace, add that service account as a subject to the rolebinding for the namespace

If `--namespace` is not set, rolebinding commands operate in the `orka-default` namespace. The shorthand alias for `rolebinding` is `rb`.

## Managing role subjects

> [!NOTE]
>
> Requires Orka 4.0 or later. On earlier versions, use the `orka rolebinding` commands that follow.

Use `orka rbac` to grant and revoke Orka roles for users and service accounts. Every `orka rbac` command requires administrative privileges and a `--role`:

* **`--role dev`** modifies the `orka-dev` rolebinding in a single namespace, granting access to that namespace. Use `--namespace` to choose the namespace. It defaults to your default namespace.
* **`--role admin`** is cluster-wide. Subjects are added to or removed from every rolebinding and cluster rolebinding that grants the admin role to its OIDC group, so `--namespace` isn't valid with `--role admin`.

### orka rbac add-subject

Grant a role to one or more users and/or service accounts.

Admin grants apply only to the admin bindings that exist at grant time. Bindings created later, for example when you create a new namespace, start without the granted subjects. Re-run this command after creating namespaces to include them. It's safe to run more than once.

**Syntax:**

```bash theme={null}
orka rbac add-subject --role admin|dev [--namespace TARGET_NAMESPACE] --user EMAIL_1[,EMAIL_2,...] AND/OR --serviceaccount SA_NAMESPACE_1:SERVICE_ACCOUNT_1[,SA_NAMESPACE_2:SERVICE_ACCOUNT_2,...] [flags]
```

**Options:**

```
-h, --help                     Display help for add-subject
-r, --role string              The role to grant: admin or dev
-n, --namespace string         (Optional) With --role dev, the namespace whose orka-dev rolebinding is modified (default: your default namespace). Not valid with --role admin
-s, --serviceaccount strings   Service accounts (NAMESPACE:SERVICE_ACCOUNT format, comma-separated)
-u, --user strings             Users (email addresses, comma-separated)
```

**Examples:**

```bash theme={null}
# Grant the 'admin' role to a service account
orka rbac add-subject --role admin --serviceaccount orka-default:sa-jenkins

# Grant the 'admin' role to a user
orka rbac add-subject --role admin --user user@company.com

# Grant the 'dev' role in the 'orka-test' namespace to a user
orka rbac add-subject --role dev --namespace orka-test --user user@company.com

# Grant the 'admin' role to multiple users and service accounts
orka rbac add-subject --role admin --user user1@company.com,user2@company.com --serviceaccount orka-default:sa-jenkins,orka-production:sa-release-builds
```

### orka rbac list-subjects

List the subjects currently granted a role. With `--role admin`, the list combines the subjects from every binding that grants the admin role, without duplicates.

**Syntax:**

```bash theme={null}
orka rbac list-subjects --role admin|dev [--namespace TARGET_NAMESPACE] [--output wide|json] [flags]
```

**Options:**

```
-h, --help               Display help for list-subjects
-r, --role string        The role to list subjects for: admin or dev
-n, --namespace string   (Optional) With --role dev, the namespace whose orka-dev rolebinding is listed (default: your default namespace). Not valid with --role admin
-o, --output string      (Optional) Output format: table (default)|wide|json
```

**Examples:**

```bash theme={null}
# List the subjects granted the 'admin' role
orka rbac list-subjects --role admin

# List the subjects granted the 'dev' role in the 'orka-test' namespace
orka rbac list-subjects --role dev --namespace orka-test
```

### orka rbac remove-subject

Revoke a role from one or more users and/or service accounts.

**Syntax:**

```bash theme={null}
orka rbac remove-subject --role admin|dev [--namespace TARGET_NAMESPACE] --user EMAIL_1[,EMAIL_2,...] AND/OR --serviceaccount SA_NAMESPACE_1:SERVICE_ACCOUNT_1[,SA_NAMESPACE_2:SERVICE_ACCOUNT_2,...] [flags]
```

**Options:**

```
-h, --help                     Display help for remove-subject
-r, --role string              The role to revoke: admin or dev
-n, --namespace string         (Optional) With --role dev, the namespace whose orka-dev rolebinding is modified (default: your default namespace). Not valid with --role admin
-s, --serviceaccount strings   Service accounts (NAMESPACE:SERVICE_ACCOUNT format, comma-separated)
-u, --user strings             Users (email addresses, comma-separated)
```

**Examples:**

```bash theme={null}
# Revoke the 'admin' role from a service account
orka rbac remove-subject --role admin --serviceaccount orka-default:sa-jenkins

# Revoke the 'admin' role from a user
orka rbac remove-subject --role admin --user user@company.com

# Revoke the 'dev' role in the 'orka-test' namespace from a user
orka rbac remove-subject --role dev --namespace orka-test --user user@company.com

# Revoke the 'admin' role from multiple users and service accounts
orka rbac remove-subject --role admin --user user1@company.com,user2@company.com --serviceaccount orka-default:sa-jenkins,orka-production:sa-release-builds
```

## Managing rolebindings

> [!WARNING]
>
> **Deprecated in Orka 4.0.** Use `orka rbac` with `--role dev` instead. The `orka rolebinding` commands still work in Orka 4.0 and behave the same as before, but each one prints a deprecation message to stderr that names its replacement, for example `Command "list-subjects" is deprecated, use "orka rbac list-subjects --role dev --namespace TARGET_NAMESPACE" instead`, and no longer appear in `orka --help`. They map to the new commands as follows:
>
> * `orka rolebinding add-subject` becomes `orka rbac add-subject --role dev`
> * `orka rolebinding list-subjects` becomes `orka rbac list-subjects --role dev`
> * `orka rolebinding remove-subject` becomes `orka rbac remove-subject --role dev`

### orka rolebinding add-subject

Add a subject to the rolebinding for the specified namespace. This grants the user or the service account access to the specified namespace.

**Syntax:**

```bash theme={null}
orka rolebinding add-subject --namespace TARGET_NAMESPACE --user EMAIL_1[,EMAIL_2,...] AND/OR --serviceaccount SA_NAMESPACE_1:SERVICE_ACCOUNT_1[,SA_NAMESPACE_2:SERVICE_ACCOUNT_2,...] [flags]
```

**Options:**

```
-h, --help                     Display help for add-subject
-s, --serviceaccount strings   Service accounts (NAMESPACE:SERVICE_ACCOUNT format, comma-separated)
-u, --user strings             Users (email addresses, comma-separated)
-n, --namespace string         (Optional) Target namespace (default "orka-default")
```

**Examples:**

```bash theme={null}
# Grant a user access to a namespace
orka rb add-subject --namespace orka-test --user user@company.com

# Grant multiple users access to a namespace
orka rb add-subject --namespace orka-test --user user1@company.com,user2@company.com

# Grant a service account access to a namespace
orka rb add-subject --namespace orka-test --serviceaccount orka-default:sa-jenkins

# Grant multiple service accounts access
orka rb add-subject --namespace orka-test --serviceaccount orka-default:sa-jenkins,orka-production:sa-release-builds

# Grant multiple users and service accounts access
orka rb add-subject --namespace orka-test --user user1@company.com,user2@company.com --serviceaccount orka-default:sa-jenkins,orka-production:sa-release-builds
```

### orka rolebinding list-subjects

List all rolebinding subjects, along with their kind, in the orka-default namespace or another specified namespace.

**Syntax:**

```bash theme={null}
orka rolebinding list-subjects [--namespace TARGET_NAMESPACE] [--output wide|json] [flags]
```

**Options:**

```
-h, --help               Display help for list-subjects
-o, --output string      (Optional) Output format: table (default)|wide|json
-n, --namespace string   (Optional) Namespace scope (default "orka-default")
```

**Examples:**

```bash theme={null}
# List subjects in the 'orka-default' namespace rolebinding
orka rb list-subjects

# List subjects in a specific namespace rolebinding
orka rb list-subjects --namespace orka-test
```

### orka rolebinding remove-subject

Remove a subject from a rolebinding. This revokes the user or service account access to the specified namespace.

**Syntax:**

```bash theme={null}
orka rolebinding remove-subject --user EMAIL_1[,EMAIL_2,...] AND/OR --serviceaccount SA_NAMESPACE_1:SERVICE_ACCOUNT_1[,SA_NAMESPACE_2:SERVICE_ACCOUNT_2,...] [--namespace TARGET_NAMESPACE] [flags]
```

**Options:**

```
-h, --help                     Display help for remove-subject
-s, --serviceaccount strings   Service accounts to remove (NAMESPACE:SERVICE_ACCOUNT format, comma-separated)
-u, --user strings             Users to remove (email addresses, comma-separated)
-n, --namespace string         (Optional) Target namespace (default "orka-default")
```

**Examples:**

```bash theme={null}
# Revoke access to a namespace for a user
orka rb remove-subject --namespace orka-test --user user@company.com

# Revoke access for multiple users
orka rb remove-subject --namespace orka-test --user user1@company.com,user2@company.com

# Revoke access for a service account
orka rb remove-subject --namespace orka-test --serviceaccount orka-default:sa-jenkins

# Revoke access for multiple service accounts
orka rb remove-subject --namespace orka-test --serviceaccount orka-default:sa-jenkins,orka-production:sa-release-builds

# Revoke access for multiple users and service accounts
orka rb remove-subject --namespace orka-test --user user1@company.com,user2@company.com --serviceaccount orka-default:sa-jenkins,orka-production:sa-release-builds
```

## Common workflows

### Adding and removing access

**Common workflow:**

1. **Create a namespace:**

```bash theme={null}
orka namespace create orka-test
```

2. **Move nodes to the namespace:**

```bash theme={null}
orka node namespace mini-1 orka-test
orka node namespace mini-2 orka-test
```

3. **Grant users access:**

```bash theme={null}
orka rb add-subject --namespace orka-test --user user@company.com
```

4. **Grant service accounts access:**

```bash theme={null}
orka rb add-subject --namespace orka-test --serviceaccount orka-default:sa-jenkins
```

5. **Verify access:**

```bash theme={null}
orka rb list-subjects --namespace orka-test
```

### Service account access

Service accounts are automatically granted access to the namespace where they are created. To grant a service account access to additional namespaces, use the rolebinding commands:

```bash theme={null}
# Create service account in orka-default
orka sa create sa-jenkins

# Grant access to orka-test namespace
orka rb add-subject --namespace orka-test --serviceaccount orka-default:sa-jenkins

# Grant access to orka-production namespace
orka rb add-subject --namespace orka-production --serviceaccount orka-default:sa-jenkins
```


## Related topics

- [Cluster Access Management: Overview](https://docs.macstadium.com/orka/orka-cluster-access/cluster-access-management-overview.md)
- [Orka release notes](https://docs.macstadium.com/orka/orka-upgrades-and-release-notes/orka-release-notes.md)
- [Orka authentication, OIDC, and RBAC configuration](https://docs.macstadium.com/orka/orka-cluster-access/orka-authentication-and-rbac.md)
- [Cluster Configurations](https://docs.macstadium.com/orka/orka-resources/cluster-configurations.md)
- [Resiliency, High Availability, and Disaster Recovery](https://docs.macstadium.com/orka/orka-resources/resiliency-high-availability-and-disaster-recovery.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.