Skip to Content

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 until someone confirms them.

A cluster

environments/prod.yaml
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
clusters/hetzner-fsn1.yaml
# 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
KeyMeaning
provider, regionWhere the cluster runs.
environmentThe environment the cluster serves. Projects on the cluster belong to it.
auto_updateAutomatic Kubernetes and Talos updates: off, patch or patch_minor.
maintenance_windowWhen updates may run: days (mon to sun), start (HH:MM), duration_minutes (60 to 480) and an IANA timezone.
load_balancersLoad balancers by type (for example lb11). A load balancer with a name is resized in place when its type changes.
poolsThe node pools. A cluster needs a control_plane pool.

Pools

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

KeyMeaning
node_typeThe machine type, from the provider's catalog.
optionsOption selections for a machine family, such as bare metal RAM or disks. Cloud types take no options.
countThe number of nodes.
block_volume_gbAn extra block volume per node, in GB.
storageThe pool's storage: strategy (zfs_local, longhorn, local_path or none) and its config.
extensionsExtra Talos system extensions.
labelsNode labels.
reservedOnly apps that name this pool run on it.
public_ipv4Give each node a public IPv4 address.
lb_targetThe 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.
autoscalingNode autoscaling, see below.
upgrade_strategyHow nodes are upgraded: auto, surge or in_place.
max_setup_fee, max_monthly_price, max_hourly_pricePrice 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

RoleRunsStorage
control_planeThe Kubernetes control plane. Every cluster needs one such pool.
workerApps. Stores no app data.none
hybridApps, and stores app data.A strategy other than none
storageStores 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 until confirmed.

Upgrade strategy

ValueUpgrade
auto (default)Surge when the pool allows it, otherwise in place.
surgeAdd a temporary node, move the workloads, then remove the old node.
in_placeUpgrade 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.

clusters/hetzner-fsn1.yaml
# 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.

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.

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

Autoscaling

clusters/hetzner-fsn1.yaml
# 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.

Storage

clusters/hetzner-fsn1.yaml
# 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 and the pool fields for every key.

On this page