> Index of every page on this site: [llms.txt](https://docs.a-line.cloud/llms.txt)

# Clusters and pools

> Describe a cluster, its node pools, load balancers and upgrade settings.

A cluster file lives in `clusters/<name>.yaml` in an infrastructure link. The
file name is the cluster's name. `name` is optional and, when set, must match
the file name. Renaming the file creates a new cluster.

Creating a cluster or a pool, and raising a pool's node count, are
[held](/iac/gitops#held) until someone confirms them.

## A cluster

```yaml title="environments/prod.yaml" iac tree=cluster
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
```

```yaml title="clusters/hetzner-fsn1.yaml" iac tree=cluster
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
provider: hetzner
region: fsn1
environment: prod
auto_update: patch
maintenance_window:
  days: [sat, sun]
  start: "02:00"
  duration_minutes: 120
  timezone: Europe/Amsterdam
load_balancers:
  - name: public
    type: lb11
pools:
  - name: control-plane
    role: control_plane
  - name: general
    node_type: cx22
    count: 3
```

| Key | Meaning |
| --- | --- |
| `provider`, `region` | Where the cluster runs. |
| `environment` | The environment the cluster serves. Projects on the cluster belong to it. |
| `auto_update` | Automatic Kubernetes and Talos updates: `off`, `patch` or `patch_minor`. |
| `maintenance_window` | When updates may run: `days` (`mon` to `sun`), `start` (`HH:MM`), `duration_minutes` (60 to 480) and an IANA `timezone`. |
| `load_balancers` | Load balancers by `type` (for example `lb11`). A load balancer with a `name` is resized in place when its type changes. |
| `pools` | The node pools. A cluster needs a `control_plane` pool. |

## Pools

Each pool has a `name` and a `role`: `control_plane`, `worker`, `storage` or
`hybrid`.

| Key | Meaning |
| --- | --- |
| `node_type` | The machine type, from the provider's catalog. |
| `options` | Option selections for a machine family, such as bare metal RAM or disks. Cloud types take no options. |
| `count` | The number of nodes. |
| `block_volume_gb` | An extra block volume per node, in GB. |
| `storage` | The pool's storage: `strategy` (`zfs_local`, `longhorn`, `local_path` or `none`) and its `config`. |
| `extensions` | Extra Talos system extensions. |
| `labels` | Node labels. |
| `reserved` | Only apps that name this pool run on it. |
| `public_ipv4` | Give each node a public IPv4 address. |
| `lb_target` | The cluster load balancer sends traffic to this pool's nodes. Off by default for reserved and build pools, on for the rest; see [load balancer targets](#lb-target). |
| `autoscaling` | Node autoscaling, see below. |
| `upgrade_strategy` | How nodes are upgraded: `auto`, `surge` or `in_place`. |
| `max_setup_fee`, `max_monthly_price`, `max_hourly_price` | Price caps for the pool's node type. |

`node_type`, `options` and `block_volume_gb` cannot change after the pool is
created. To change them, add a new pool, move the apps and remove the old
pool. The old `machine:` key is refused: use `node_type` plus `options`.

### Roles

| Role | Runs | Storage |
| --- | --- | --- |
| `control_plane` | The Kubernetes control plane. Every cluster needs one such pool. | |
| `worker` | Apps. Stores no app data. | `none` |
| `hybrid` | Apps, and stores app data. | A strategy other than `none` |
| `storage` | Stores app data. | A strategy other than `none` |

A role and storage that don't match are refused with
`role_storage_mismatch`. Only `worker` and `hybrid` can switch into each
other, and the storage follows: `hybrid` to `worker` drops the storage to
`none`, `worker` to `hybrid` needs a storage strategy. Any other role change
is refused with `role_change_unsupported`. Role and storage switches are
[held](/iac/gitops#held) until confirmed.

### Upgrade strategy

| Value | Upgrade |
| --- | --- |
| `auto` (default) | Surge when the pool allows it, otherwise in place. |
| `surge` | Add a temporary node, move the workloads, then remove the old node. |
| `in_place` | Upgrade each node where it stands. |

A pool allows a surge only when all of these hold:

- the node type is billed by the hour, with no setup fee and no minimum term;
- it is delivered within 10 minutes and is not bare metal;
- the pool has no active commitment;
- its storage is not `zfs_local` or `local_path`, and it has no
  `block_volume_gb`;
- a control-plane pool has at least two nodes.

Longhorn pools can surge: their replicas are rebuilt before the old node is
removed. `surge` on a pool that fails a billing rule is refused, because the
temporary node would be charged a whole term or a setup fee; use `auto` or
`in_place`. On a pool that fails another rule, `surge` upgrades in place.

### Bare metal

A machine family takes its option selections in `options`. The valid keys
and values come from the node type's catalog entry; an option the type does
not offer is refused with the list of available ones.

```yaml title="clusters/hetzner-fsn1.yaml" iac tree=bare-metal
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
provider: hetzner
region: fsn1
pools:
  - name: control-plane
    role: control_plane
  - name: general
  - name: builds
    node_type: ex44
    options:
      ram: 64gb
    count: 1
    reserved: true
```

Bare metal machines can come with a setup fee and a minimum term. A committed
machine stays billed until the end of its term, even after you remove it, and
the confirm dialog asks you to acknowledge that.

### Reserved pools

A `reserved` pool only runs apps that name it in their `pool` key. Use it to
keep builds, databases or noisy workloads apart from everything else. An app
pins itself with `pool: builds`; see [placement](/iac/apps#placement).

### Load balancer targets

The cluster load balancer sends ingress traffic to the nodes of every pool
with `lb_target` on. Pools that run no ingress, such as storage or name
server pools, should leave it off, or their nodes show as unhealthy targets.
Reserved and build pools start with it off; every other pool starts with it
on. Leave the key out to keep a pool's current value.

Changing it relabels the pool's existing nodes in place; no node is replaced,
so static addresses stay.

```yaml
pools:
  - name: data
    role: storage
    node_type: cx33
    count: 3
    lb_target: false
```

### Autoscaling

```yaml title="clusters/hetzner-fsn1.yaml" iac tree=autoscaling
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
provider: hetzner
region: fsn1
pools:
  - name: control-plane
    role: control_plane
  - name: general
    node_type: cx32
    autoscaling:
      enabled: true
      min: 2
      max: 6
      scale_up_cpu_percent: 75
      scale_down_cpu_percent: 30
      allow_scale_down: true
```

`min` and `max` bound the node count. The `scale_up_*` and `scale_down_*`
percentages set the CPU and memory usage at which nodes are added or removed;
`allow_scale_down: false` keeps the pool from shrinking.

Raising `max` is held like a node count increase, unless the infrastructure
link [applies billable changes without confirmation](/iac/gitops#auto-apply).

### Storage

```yaml title="clusters/hetzner-fsn1.yaml" iac tree=storage
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
provider: hetzner
region: fsn1
pools:
  - name: control-plane
    role: control_plane
  - name: data
    role: storage
    node_type: cx42
    count: 3
    storage:
      strategy: longhorn
```

See the [cluster file reference](/iac/reference/cluster-file) and the
[pool fields](/iac/reference/types#infrapoolspec) for every key.
