Skip to content

Commit 3f158c9

Browse files
committed
feat(charts): add preset value knobs (#226-#230)
Expose operator-visible values on the cozystack, generic, and talm charts so a node's Talos config can be described from values.yaml instead of forking the template: - timeServers: machine.time.servers - extra{ApiServer,ControllerManager,Scheduler}Args: passthrough control-plane component args, coerced to strings (Talos wants map[string]string) and guarded against colliding with preset built-ins - registryMirrors: declarative machine registry mirrors (the default docker.io -> mirror.gcr.io is preserved) - registryTLS: TLS posture per registry endpoint host, keyed by endpoint hostname rather than mirror name so a self-signed pull-through cache can be trusted without touching the mirror list - vips: multiple Layer2 VIPs, each pinned to a link - network.preserveExisting: emit the running interfaces verbatim - network.extraLinks: declare bonds, VLANs, and extra addresses, with the same bond tuning the discovery path reconstructs (xmitHashPolicy, lacpRate, miimon, updelay, downdelay) plus mtu and routes on both a link and its VLAN children, so an externally-routed tagged uplink is expressible without a template fork Every knob defaults empty so a stock render stays byte-identical, pinned by TestGoldenRender. Each input Talos would reject fails fast at render with a hinted message: extraArgs colliding with a built-in, a duplicate or dangling VIP, a VIP on a link already in the running config, a VLAN on a missing parent, an empty bond, a route with no gateway, a malformed registry entry, or a registryTLS entry that leaves its security posture unstated. Contract tests cover the happy and rejected paths across the legacy and multi-doc schemas for both presets. An extraLinks bond slave gets no document of its own, matching the filter discovery applies once the bond exists. Moving an already-addressed NIC into a bond works once the entry restates where its addressing goes; the render fails, naming the addresses and the gateway to restate, rather than dropping the node's connectivity. VIP addresses are compared canonically, so a VIP spelled differently from what the node reports is still stripped from the static addresses rather than shipping twice. pkg/applycheck learns which links a config creates, so a VLANConfig.parent, BondConfig.links[] or Layer2VIPConfig.link pointing at one of them resolves instead of blocking the first apply — without it a declared bond is unusable. A LinkAliasConfig name ending in %d is registered as a pattern, because Talos expands it into one alias per matched link. Assisted-By: Claude <[email protected]> Signed-off-by: Aleksei Sviridkin <[email protected]>
1 parent c2d0f05 commit 3f158c9

17 files changed

Lines changed: 4142 additions & 52 deletions

‎README.md‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -160,29 +160,31 @@ cluster:
160160
> - **Talos < v1.12** — single YAML document with `machine.network` and `machine.registries` sections (as shown above).
161161
> - **Talos >= v1.12** — multi-document format with separate typed documents instead of the deprecated monolithic fields.
162162
>
163-
> For v1.12+ multi-doc output, one document is emitted per configurable link on the node, plus a fixed pair on every render:
163+
> For v1.12+ multi-doc output, one document is emitted per configurable link on the node, plus any link declared through `network.extraLinks` and a fixed pair on every render:
164164
>
165165
> - `HostnameConfig` and `ResolverConfig` — always emitted.
166166
> - `LinkConfig` — physical NICs.
167167
> - `BondConfig` — bond masters. Bond slaves are filtered out so they do not collide with the master's document.
168168
> - `VLANConfig` — VLAN sub-interfaces.
169169
> - `BridgeConfig` — bridges, symmetric to `BondConfig` for bonds. Ports discovered via `spec.slaveKind == "bridge"` + `spec.masterIndex`; STP / VLAN-filtering settings reach the output when the bridge controller reports them on `spec.bridgeMaster`.
170-
> - `Layer2VIPConfig` — controlplane nodes when `floatingIP` is set.
171-
> - `RegistryMirrorConfig` — cozystack chart only.
170+
> - `Layer2VIPConfig` — one per VIP. The `floatingIP` shorthand emits it on controlplane nodes; each `vips` entry emits one on any node, so a storage VIP works on a worker.
171+
> - `RegistryMirrorConfig` and `RegistryTLSConfig` — from the `registryMirrors` and `registryTLS` values, available on both charts.
172172
>
173173
> Per-link emission rules:
174174
>
175175
> - The link carrying the IPv4 default route gets the `routes.gateway` entry on its document; every other link is emitted gateway-less. Applies uniformly to `LinkConfig`, `BondConfig`, `VLANConfig`, `BridgeConfig`.
176176
> - Both IPv4 and IPv6 global-scope addresses on a link are surfaced.
177-
> - The operator-declared `floatingIP` is stripped from per-link addresses so the VIP currently held by a leader does not leak into the static document.
177+
> - Every declared VIP ip (`floatingIP` plus each `vips[].ip`) is stripped from the addresses discovery reports, so a VIP currently held by a leader does not leak into the static document. Addresses are compared canonically, so a VIP spelled differently from what the node reports (`2001:0DB8::5` against `2001:db8::5/64`) is still recognised. An address the operator writes by hand under `network.extraLinks` is refused rather than stripped — the render does not silently drop what it was told to emit.
178178
>
179179
> Multi-NIC nodes therefore produce one document per NIC, not one document total.
180+
>
181+
> Two values change this shape. `network.extraLinks` declares links that discovery cannot see — a bond, VLAN or address the node does not carry yet — so documents are emitted for links that are not (or not yet) on the node. A link named in `bond.interfaces` becomes a slave and stops getting a document of its own, the same filter discovery applies once the bond exists. Moving an already-addressed NIC into a bond works, provided the entry restates where its addressing goes — a slave carrying addresses needs `addresses` on the bond entry, one carrying the default route needs a `routes` entry there as well, and the render fails rather than dropping the node's connectivity if either is missing. `network.preserveExisting` goes the other way: the running `machine.network.interfaces` block is carried over verbatim and the typed per-link rebuild is skipped entirely, so no per-link document is emitted at all. VIP and registry documents are unaffected by either.
180182

181183
> **Version compatibility (`templateOptions.talosVersion` / `--talos-version`).** This setting must match the **Talos version actually running on the target node** — i.e. the maintenance ISO/PXE the node booted from for `apply -i`, or the installed Talos for an authenticated apply. It is **not** the same as `install.image`, which only controls what gets written to disk after a successful apply. When the configured contract is newer than the running binary, machinery injects fields (e.g. `machine.install.grubUseUKICmdline` from v1.12) that the running parser does not know, and the apply fails on the node side with `failed to parse config: unknown keys found during decoding: ...`. `talm apply` runs a best-effort pre-flight check against the running version and prints a `warning: pre-flight: ...` line with a hint when it detects this mismatch; if the warning is missed, the same hint is appended to the apply error. Either reboot the node into a maintenance image that matches the configured contract, or lower `templateOptions.talosVersion` / `--talos-version` to match what is running.
182184

183185
> **Apply-time safety gates.** `talm apply` and `talm upgrade` run additional gates around each operation:
184186
>
185-
> 1. **Declared-resource existence** (`--skip-resource-validation` opt-out, default on). Before sending the config to the node, the gate walks the rendered MachineConfig, extracts every reference to a host-side resource (network links from v1.12 multi-doc — `LinkConfig.name`, `BondConfig.links[]`, `VLANConfig.parent`, `BridgeConfig.links[]`, `Layer2VIPConfig.link`, `HCloudVIPConfig.link`, `DHCPv4Config.name` / `DHCPv6Config.name` / `EthernetConfig.name`; v1.11 legacy `machine.network.interfaces[].interface`; install disk via `machine.install.disk` literal or `machine.install.diskSelector`; `UserVolumeConfig.provisioning.diskSelector`), and verifies each against the node's COSI `LinkStatus`/`Disk` snapshots. A reference that doesn't resolve fails the apply with a `[blocker]` line listing the available names so the typo or migration miss is fixable from the values without re-running discovery. Disk selectors must match at least one (non-readonly, non-CDROM, non-virtual) disk — zero matches block, multiple matches warn (install picks the first). Virtual-link-creator documents (`BondConfig.name`, `VLANConfig.name`, `BridgeConfig.name`, `WireguardConfig.name`, `DummyLinkConfig.name`, `LinkAliasConfig.name`) are intentionally NOT validated against existing links — those `.name` fields describe new virtual links the apply is creating, not references to pre-existing host resources. The gate also runs a syntactic net-addr walker against `StaticHostConfig.name` (must parse as an IP literal — the `name` field on this kind doubles as the IP the hostnames map to), `NetworkRuleConfig.ingress[].subnet` and `.except` (per-entry CIDR), and `WireguardConfig.peers[].endpoint` (host:port; empty / absent endpoint is a listener-only peer, NOT a finding). Out of scope today: `machine.disks[].device` (extra-disk partitioning); track in a follow-up if you need it. Pass `--skip-resource-validation` for recovery into a maintenance image with mismatched hardware or pre-staging values for hardware that isn't installed yet.
187+
> 1. **Declared-resource existence** (`--skip-resource-validation` opt-out, default on). Before sending the config to the node, the gate walks the rendered MachineConfig, extracts every reference to a host-side resource (network links from v1.12 multi-doc — `LinkConfig.name`, `BondConfig.links[]`, `VLANConfig.parent`, `BridgeConfig.links[]`, `Layer2VIPConfig.link`, `HCloudVIPConfig.link`, `DHCPv4Config.name` / `DHCPv6Config.name` / `EthernetConfig.name`; v1.11 legacy `machine.network.interfaces[].interface`; install disk via `machine.install.disk` literal or `machine.install.diskSelector`; `UserVolumeConfig.provisioning.diskSelector`), and verifies each against the node's COSI `LinkStatus`/`Disk` snapshots. A reference that doesn't resolve fails the apply with a `[blocker]` line listing the available names so the typo or migration miss is fixable from the values without re-running discovery. Disk selectors must match at least one (non-readonly, non-CDROM, non-virtual) disk — zero matches block, multiple matches warn (install picks the first). Virtual-link-creator documents (`BondConfig.name`, `VLANConfig.name`, `BridgeConfig.name`, `WireguardConfig.name`, `DummyLinkConfig.name`, `LinkAliasConfig.name`) are intentionally NOT validated against existing links — those `.name` fields describe new virtual links the apply is creating, not references to pre-existing host resources. Five of them (`BondConfig`, `VLANConfig`, `BridgeConfig`, `DummyLinkConfig`, `LinkAliasConfig`) additionally register their `.name` as a link this apply brings into existence, so a `VLANConfig.parent`, `BondConfig.links[]` or `Layer2VIPConfig.link` pointing at one of them resolves rather than blocking. That is what makes a `network.extraLinks` bond usable on first apply, before the node carries it. A `LinkAliasConfig` name ending in `%d` is registered as a pattern rather than a literal, because Talos expands it into one sequential alias per matched link (`net0`, `net1`, …) — so a reference to `net0` resolves while the literal `net%d`, which never exists on the node, is not treated as a link. `WireguardConfig` is the exception: it is handled by the net-addr walker (for its `peers[].endpoint`), which stays disjoint from the link walker, so it does not register its name — a VLAN or VIP layered on a wireguard link still blocks on first apply and needs `--skip-resource-validation` until the link exists. The gate also runs a syntactic net-addr walker against `StaticHostConfig.name` (must parse as an IP literal — the `name` field on this kind doubles as the IP the hostnames map to), `NetworkRuleConfig.ingress[].subnet` and `.except` (per-entry CIDR), and `WireguardConfig.peers[].endpoint` (host:port; empty / absent endpoint is a listener-only peer, NOT a finding). Out of scope today: `machine.disks[].device` (extra-disk partitioning); track in a follow-up if you need it. With `network.preserveExisting` the rendered config carries the running `machine.network.interfaces` block instead of typed per-link documents, so the gate validates the legacy `interface` fields from that block. Pass `--skip-resource-validation` for recovery into a maintenance image with mismatched hardware or pre-staging values for hardware that isn't installed yet.
186188
>
187189
> 2. **Pre-apply drift preview** (`--skip-drift-preview` opt-out, default on). Reads the node's current MachineConfig via COSI and prints a `+`/`-`/`~`/`=` diff of what's about to change, keyed by `(kind, name)`. Informational only — never blocks. The `-` lines are the most useful: they surface stale documents from a previous apply that the new render no longer emits (e.g. an `eth1` LinkConfig lingering after a migration to `eth0`). Reading the current config requires the auth path — `MachineConfig` is a Sensitive COSI resource and is unreachable on the `--insecure` maintenance connection; the gate prints `drift verification unavailable on maintenance connection` (per-node-prefixed on multi-node insecure apply) and proceeds in that case. Secret-bearing field values (`cluster.token`, `cluster.{ca,aggregatorCA,serviceAccount,etcd.ca}.key`, `machine.token` / `machine.ca.key`, the `cluster.acceptedCAs` / `machine.acceptedCAs` slices, `WireguardConfig.privateKey`, the `peers` slice carrying `presharedKey`s) are redacted by default — both sides render as `***redacted (len=N)***` so a rotation surfaces as different-length sentinels without leaking the value. In addition to that static path allowlist, any value originating from an encrypted user value file (`*.encrypted.yaml` referenced via `templateOptions.valueFiles`) is redacted **by value** wherever it surfaces in the diff (at any path, including nested in a slice) — symmetric with how `talm template` redacts the same values. Pass `--show-secrets-in-drift` to see the raw values verbatim (debugging only — disables both the path-based and value-based redaction for the run). **`--dry-run` runs this gate** — the diff is read-only and "show me what would change" is exactly the dry-run contract.
188190
>

0 commit comments

Comments
 (0)