# Cluster Configuration

> Cordium documentation. Canonical page: <https://octelium.com/docs/cordium/latest/use/clusterconfig>.

`ClusterConfig` acts as the sole source of truth for all global configurations and settings for the Cordium Cluster. It controls Space ownership policy, Workspace storage class selection, cluster-wide resource limits, and Workspace timeouts. There is exactly one `ClusterConfig` per Cordium Cluster. It is created automatically at installation time and updated via `cordium man apply`.

```bash
cordium man apply </PATH/TO/CONFIG.YAML>
```

## Space

### Ownership

The `ownership` field defines a policy that controls which users are allowed to create Spaces. It contains a list of `rules`, each with an `effect` (`ALLOW` or `DENY`) and a `condition` expressed in CEL. Rules are evaluated in order. The first rule whose condition matches the requesting user determines the outcome. If no rule matches, the request is denied by default.

This field is optional. If omitted, Space creation is unrestricted.

```yaml
spec:
  space:
    ownership:
      rules:
        # Allow users in the "engineers" group to create Spaces
        - effect: ALLOW
          condition:
            match: '"engineers" in ctx.user.spec.groups'

        - effect: DENY
          condition:
            match: "true"
```

Here is another example of permissive configuration that allows all Users to create Spaces:

```yaml
spec:
  space:
    ownership:
      rules:
        - effect: ALLOW
          condition:
            allowAny: true
```

## Workspace

### Storage

Storage class selection is rule-based. Cordium evaluates the `storageClass` and `volumeSnapshotClass` rule lists in order and uses the first matching rule. This allows different storage tiers to be assigned based on Workspace attributes such as requested storage size, user identity, or Space type.

Selects the Kubernetes `StorageClass` used to provision the Workspace PVC. Each rule has a CEL `condition` evaluated against the Workspace context and a `storageClass` string naming the target `StorageClass`.

```yaml
spec:
  workspace:
    storage:
      storageClass:
        rules:
          # Use fast NVMe-backed storage for large Workspaces
          - condition:
              match: "ctx.workspace.spec.limit.storage.megabytes > 51200"
            storageClass: longhorn-nvme

          # Default to standard storage for everything else
          - condition:
              matchAny: true
            storageClass: longhorn-standard
```

You can also set the `VolumeSnapshotClass` used for Template pre-builds and Workspace snapshots. If no rule matches or this field is omitted, Kubernetes selects the default snapshot class for the volume's CSI driver. The quick installer with `--longhorn` configures `longhorn-snapshot-vsc` as that default. If your storage driver has no default snapshot class, select one explicitly. Here is an example:

```yaml
spec:
  workspace:
    storage:
      volumeSnapshotClass:
        rules:
          - condition:
              matchAny: true
            volumeSnapshotClass: longhorn-snapshot-vsc
```

### Limit

You can set Cluster-wide Workspace limits. All fields are optional. Omitting a field means no cluster-level restriction is applied for that dimension. Here is an example:

```yaml
spec:
  workspace:
    limit:
      maxPerUser: 30
      maxActivePerUser: 5

      # Resource limits for Template pre-build Workspaces
      buildLimit:
        cpu:
          millicores: 4000
        memory:
          megabytes: 8192
        storage:
          megabytes: 51200

      # Default limits for Workspaces in user-owned Spaces
      defaultUserSpaceLimit:
        cpu:
          millicores: 2000
        memory:
          megabytes: 4096
        storage:
          megabytes: 20480

      # Hard cap where no Workspace in the cluster can exceed these values
      maxLimit:
        cpu:
          millicores: 16000
        memory:
          megabytes: 32768
        storage:
          megabytes: 204800
```

### Timeout

You can also set Cluster-wide Workspace active duration limits. These define how long a Workspace can remain running before it is automatically stopped. All fields are optional. Here is an example:

```yaml
spec:
  workspace:
    timeout:
      defaultDuration:
        hours: 24
      userSpaceDuration:
        hours: 24
      maxActiveDuration:
        days: 30
```

## API Reference

[ClusterConfig JSON Schema (Cordium cordium/v1, latest documentation)](https://octelium.com/schemas/cordium/latest/cordium.v1.ClusterConfig.schema.json)