0092. Approval sets the primary NIC, its addressing and extra disk roles as typed spec fields

Status: Accepted · Date: 2026-10-27 · Design section: Nodes (approval, disk roles)

Decided: TalosMachine.spec.network (one primary link chosen by permanent MAC, DHCP or static addressing, optional VLAN, DNS servers) and TalosMachine.spec.disks (roles ephemeral and userVolume on disks identified like spec.install.disk) are written at approval by the UI form and ichor machine approve flags; pkg/render emits a LinkAliasConfig alias net0 with a CEL selector on the permanent MAC and refers to the alias from DHCPv4Config, LinkConfig, VLANConfig and ResolverConfig, a VolumeConfig for EPHEMERAL and a UserVolumeConfig per volume, and the legacy machine.network.interfaces before the multi-document contract; link addressing documents are classified live in pkg/fieldmeta, aliases and everything else keep the reboot-required default; bonds, the storage role and unused are not done

Context

ADR 0077 gave approval the system disk and left the rest of the design's approval step ("role, labels, disk roles and basic networking") without a field to carry it, so the form could not say which NIC to use or how to address it, and a node with a second disk could not put EPHEMERAL or a data volume on it.

Decision

1. spec.network {mac, addressing, addresses, gateway, dnsServers, vlanID}. mac is the link's permanent address (pattern in the CRD). addressing is dhcp (default) or static; static needs at least one address (isCIDR) and dhcp takes no addresses or gateway (CEL on the struct). gateway and each DNS server are isIP. vlanID is 1 to 4094. Unset leaves Talos's default. The field is mutable in the CRD; what a change costs is the fieldmeta classification below, not an admission rule.
2. spec.disks[] {role, disk, name, maxSize}. role is ephemeral or userVolume; disk is the same one-of selector as spec.install.disk. A user volume needs a name (letters, digits, hyphen, at most 32, mounted at /var/mnt/<name>) and may carry maxSize (200GiB, MiB/GiB/TiB). At most eight entries, one ephemeral, unique names (CEL). Whether the system disk and an ephemeral disk differ is not expressible in CEL (the two selectors can name one disk differently), so the UI checks it and Talos decides otherwise.
3. Network rendering, from the multi-document contract (MultidocNetworkConfigSupported, Talos above 1.11, so both v1.13 and v1.14):
   • LinkAliasConfig net0, selector mac(link.permanent_addr) == "<lower-case mac>", parsed against celenv.LinkLocator() so a wrong expression fails at render. This is the fix for interface names changing.
   • DHCP: DHCPv4Config named by the alias (IPv4 only; DHCPv6 is not requested).
   • Static: LinkConfig for net0 with up: true, the addresses, and a default route when a gateway is set.
   • VLAN: the alias gets a LinkConfig with up: true and nothing else, and a VLANConfig net0.<id> with parent: net0 carries the addresses and routes, or has a DHCPv4Config of its own.
   • DNS servers: a ResolverConfig nameservers list, merged into the generator's own ResolverConfig. Contract 1.11 and older render one machine.network.interfaces entry with deviceSelector.permanentAddr, the VLAN under it, and machine.network.nameservers; the legacy default route is 0.0.0.0/0 or ::/0 by gateway family.
4. Disk rendering: a VolumeConfig named EPHEMERAL whose provisioning.diskSelector.match is the same CEL expression spec.install uses (diskExpression), which replaces the generator's own EPHEMERAL document by merge; a UserVolumeConfig per volume with that selector, grow: true, maxSize if given, otherwise minSize: 1GiB because Talos refuses a user volume with neither. These are emitted for every contract, as the documents exist well before 1.12.
5. fieldmeta (pkg/fieldmeta), read against the Talos v1.14.3 controllers in internal/app/machined/pkg/controllers/network: LinkConfig, VLANConfig and DHCPv4Config are safe (link_config.go, address_config.go, route_config.go, operator_config.go take the active MachineConfig as a weak input and rewrite their specs on every change, and link_spec.go, address_spec.go, route_spec.go, operator_spec.go program the kernel); ResolverConfig.nameservers is safe on the same grounds as the existing machine.network.nameservers rule (resolver_config.go). LinkAliasConfig is left at the reboot-required default although link_alias_config.go also reacts live, because it renames the handle every other document uses. ResolverConfig.hostDNS and the volume kinds are unchanged: VolumeConfig.provisioning is already install-time-only and UserVolumeConfig keeps the default, as the design says a new user volume on an unused disk needs no reset. "Safe" is about the reboot, not about reachability: an address change on the link the controller dials moves the node (ADR 0086 covers re-finding it).
6. Approval. ApproveMachineRequest.network and .disks, mirrored on Machine; TalosLink.permanent_mac is new on the wire (the details RPC showed the current MAC, which differs for a bond member or a spoofed address). The backend re-checks everything the CRD checks and requires the MAC to be one of the machine's discovered identity MACs, so a typo is InvalidArgument with the reason. CLI: --nic MAC, --address CIDR (repeatable; any address makes it static), --gateway, --dns (repeatable), --vlan, --ephemeral-disk DISK, --user-volume NAME=DISK[,size=200GiB] (repeatable), with DISK in the --install-disk syntax. UI: a card picker listing physical links as name, MAC and speed (a typed MAC if the node reports none), address fields, and disk pickers from the disks GetNode reads.
7. Layer. Network and disk documents are system layer, applied with the install document and below every patch, so a TalosConfigPatch can still override them.

Not done

• Bonds. The design says a bond takes members by name or alias and a MAC form emits one alias per member; that needs a second link, a mode and a BondConfig, and is its own change.
• The storage role (needs a TalosStorage preset, ADR 0050), unused (no document to render) and RawVolumeConfig.
• Whether Talos still runs its default DHCP on a link that has a LinkConfig but no DHCPv4Config was not traced in operator_config.go; static addressing is rendered as written and not checked against a node.
• No end-to-end run on a real node. The documents are validated by Talos's own machinery at render time and the golden tests check their content at v1.14, v1.13 and v1.11.
• The "accepted, no effect" report for an edited EPHEMERAL selector on an installed node (design, Nodes) is not part of this change; VolumeConfig.provisioning is already classified install-time-only.
• The details RPC only reports links of a maintenance-mode node through the insecure API, so a node whose Talos API is unreachable gets a typed MAC.