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
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1# 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. |
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 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_localorlocal_path, and it has noblock_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-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: trueBare 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: falseAutoscaling
# 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: truemin 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
# 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: longhornSee the cluster file reference and the pool fields for every key.