Infrastructure

Talos Linux

The cluster runs Talos Linux v1.14.0 with Kubernetes v1.36.1. Talos is a purpose-built, immutable operating system for Kubernetes: it has no shell, no SSH, and no package manager, and all management goes through its gRPC API.

The node lifecycle (render, apply, upgrade, reset, bootstrap) is managed with topf. talosctl is only used for read-only diagnostics.

Why Talos

Layout

Everything for the cluster lives in talos/pitower/:

talos/pitower/
├── topf.yaml            # cluster name, endpoint, versions, schematic, node list
├── secrets.sops.yaml    # cluster secrets (CA, tokens), SOPS + age
├── all/                 # patches for every node
│   ├── 01-general.yaml        # kubelet, containerd, host DNS, sysctls
│   ├── 02-hostname.yaml.tpl   # hostname from topf.yaml
│   └── 03-network.yaml.tpl    # VLAN 20, VIP, dual-stack subnets
├── control-plane/       # patches for worker-01..03
│   ├── 01-cluster.yaml        # etcd, API server, reserved resources, CNI/kube-proxy off
│   └── 02-uinput.yaml         # /dev/uinput for Sunshine
├── node/<host>/         # per-node patches (install disk, labels, taints, volumes)
├── extensions/          # Image Factory schematics
├── addons/              # Cilium + kubelet-csr-approver, applied at bootstrap
└── justfile             # recipes, imported from ../talos.justfile

topf.yaml

topf.yaml is the single source for the cluster definition:

clusterName: pitower
clusterEndpoint: https://10.20.10.0:6443
kubernetesVersion: 1.36.1
talosVersion: 1.14.0
schematicId: "@extensions/amd.yaml"
secretsPath: secrets.sops.yaml

nodes:
  - host: worker-01
    ip: 10.20.10.1
    role: control-plane
    data:
      mac: "1c:83:41:40:88:41"
      lanLinks: [enp4s0]
  - host: worker-04
    ip: 10.20.10.4
    role: worker
    schematicId: "@extensions/intel.yaml"
    ...

Each node has a host name, IP, role, an optional schematicId override, and free-form data (MAC address, untagged-LAN links, untagged: true for worker-07) that the .tpl patches read. topf decrypts secrets.sops.yaml itself through sops, using SOPS_AGE_KEY_FILE.

Factory Schematics

Each node type boots a custom image from the Image Factory. The schematic YAML in extensions/ declares the system extensions and overlays; topf resolves @extensions/<file>.yaml to a schematic ID locally.

Patch Layering

Talos 1.14 uses multi-document machine configs. topf runs talosctl gen config against each node's running version, then layers the patches in order: all/, then control-plane/ (control planes only), then node/<host>/. Files ending in .tpl are Go templates rendered with the node's entry from topf.yaml.

flowchart TD
    A[topf.yaml + secrets.sops.yaml] --> B[talosctl gen config]
    B --> C[all/*]
    C --> D{role}
    D -->|control-plane| E[control-plane/*]
    D -->|worker| F[node/<host>/*]
    E --> F
    F --> G[Machine config per node]

To inspect the result without applying anything:

just talos pitower render   # full configs to output/
just talos pitower diff     # pending changes per node (topf apply --dry-run)

Key Patches

All Nodes (all/)

Control Plane (control-plane/)

Per-Node Patches

Patches in node/<host>/ apply to one node. Every node has an UnattendedInstallConfig selecting its install disk, plus whatever is specific to it:

Diagnostics

talosctl needs a talosconfig, which topf generates:

just talos pitower talosconfig         # writes talos/pitower/output/talosconfig
just talos pitower members             # cluster members
just talos pitower health              # talosctl health
just talos pitower services 10.20.10.7 # services on one node