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

# Orka namespace management with the CLI

> Create, list, and delete Orka namespaces with the orka CLI, and learn which namespace a command uses by default. Covers isolation and rolebindings.

**Admin only:** All namespace operations require administrative privileges.

## Understanding namespaces

Namespaces are used for grouping and dedicating resources to specific Orka users or service accounts. All users have access to the `orka-default` namespace. Based on specific rolebindings, a user or a service account might also be able to access the resources within additional namespaces.

**Key concepts:**

* **Resource isolation:** VMs, nodes, and resources in one namespace are separate from other namespaces
* **Access control:** Users and service accounts must be granted access to namespaces via rolebindings
* **Default namespace:** All users have access to `orka-default` by default
* **Custom pods:** Some namespaces can be configured to run custom Kubernetes resources instead of Orka VMs

**All cluster namespaces must have the `orka-` prefix.**

## Which namespace a command uses

The following commands pick their namespace in this order: `vm`, `node`, `imagecache`, `registrycredential`, `rolebinding`, and `serviceaccount`. In Orka 4.0, so do `emulator`, and `rbac add-subject`, `list-subjects`, and `remove-subject` with `--role dev`. The first one that's set wins:

1. The `--namespace` (`-n`) flag on the command.
2. The `ORKA_DEFAULT_NAMESPACE` environment variable.
3. The namespace set on the `orka` context in your kubeconfig.
4. `orka-default`.

This applies to every user, not only admins. To make a namespace your default without passing `--namespace` every time, set the environment variable, for example in your shell profile:

```shell theme={null}
export ORKA_DEFAULT_NAMESPACE=<NAMESPACE>
```

You can also set the namespace on the `orka` context with `kubectl config set-context orka --namespace=<NAMESPACE>`, but `orka user login` and `orka user set-token` reset it to `orka-default` each time they run. Use the environment variable for a default that lasts.

Because the environment variable takes precedence over the kubeconfig context, unset `ORKA_DEFAULT_NAMESPACE` if commands keep running in a namespace you didn't expect.

> [!NOTE]
>
> `orka upgrade service` doesn't follow this order. Its `--namespace` flag always defaults to `orka-default`, and it ignores the environment variable and the kubeconfig context.

## Creating namespaces

### orka namespace create

Create a new namespace with the specified name.

**Namespace name requirements:**

* Begins with the `orka-` prefix
* Does not exceed 63 characters (including the prefix)
* Consists of lowercase alphanumeric characters or dashes (-)
* Ends with an alphanumeric character
* Must be unique to the cluster

If `--enable-custom-pods` is set, creates a new namespace dedicated to running custom K8s resources (formerly sandboxing). Orka VMs cannot be deployed in that namespace.

**After creating a namespace:**

1. Move one or more nodes to the namespace to provide computational resources:

```bash theme={null}
orka node namespace NODE --namespace NAMESPACE
```

2. Provide explicit access to users or service accounts:

```bash theme={null}
orka rolebinding add-subject --namespace NAMESPACE --user EMAIL
orka rolebinding add-subject --namespace NAMESPACE --serviceaccount SA_NAMESPACE:SERVICE_ACCOUNT
```

**Syntax:**

```bash theme={null}
orka namespace create NAMESPACE_NAME [flags]
```

**Options:**

```
--enable-custom-pods   Configure namespace for custom pods (formerly sandboxing)
-h, --help             Display help for create
```

**Examples:**

```bash theme={null}
# Create a new namespace
orka namespace create orka-test

# Create a namespace for custom pods (cannot run Orka VMs)
orka namespace create orka-cp --enable-custom-pods
```

## Listing namespaces

### orka namespace list

List all namespaces for the Orka cluster. Use this command to check if one or more specific namespaces already exist.

**Syntax:**

```bash theme={null}
orka namespace list [NAMESPACE_1 [NAMESPACE_2 ...]] [--output wide|json] [flags]
```

**Options:**

```
-h, --help            Display help for list
-o, --output string   (Optional) Output format: table (default)|wide|json
```

**Examples:**

```bash theme={null}
# List existing namespaces for your Orka cluster
orka namespace list

# Check if a specific namespace exists
orka namespace list orka-test

# Check if several specific namespaces exist
orka namespace list orka-test orka-production
```

## Deleting namespaces

### orka namespace delete

Delete the specified namespace. All VMs (or custom pods) must be removed and nodes must be moved out of the namespace before running this operation.

> [!WARNING]
>
> This is a destructive operation and cannot be undone. To restore a deleted namespace, re-create it, move the respective Orka nodes, and re-add the respective users to the respective role bindings.

**Syntax:**

```bash theme={null}
orka namespace delete NAMESPACE_NAME [NAMESPACE_2 ...] [flags]
```

**Options:**

```
-h, --help               Display help for delete
-t, --timeout duration   (Optional) Time to wait before giving up (default 1h0m0s)
```

**Examples:**

```bash theme={null}
# Delete a namespace
orka namespace delete orka-test

# Delete multiple namespaces
orka namespace delete orka-test orka-production
```


## Related topics

- [Orka node management with the CLI](https://docs.macstadium.com/orka/orka-cli-reference/node-management.md)
- [Authentication and User Management](https://docs.macstadium.com/orka/orka-cli-reference/authentication-and-user-management.md)
- [Orka CLI command quick reference](https://docs.macstadium.com/orka/orka-cli-reference/command-quick-reference.md)
- [Kubernetes-native Orka resource management](https://docs.macstadium.com/orka/kubernetes-native/k8s-native-overview.md)
- [VM Lifecycle Management](https://docs.macstadium.com/orka/orka-cli-reference/vm-lifecycle-management.md)


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