talos-config-editing

name	talos-config-editing
description	How to edit Talos node configs in this repo: which file for which change, strategic merge patch rules, and how to add new config documents.
when_to_use	Trigger phrases: "edit talos config", "add talos extension", "change sysctl", "modify kubelet", "add node label", "talos machine config", "new config document", "ExtensionServiceConfig", "talos patch", "per-node config".

Editing Talos Config

Three-Layer Pipeline

task talos:generate builds each node's final config as:

envsubst < templates/controlplane.yaml                      → base v1alpha1 document
talosctl machineconfig patch … --patch @nodes/{name}.yaml   → node-specific overrides
envsubst < templates/extension-nut-client.yaml >> …         → appended ExtensionServiceConfig doc
mv … clusterconfig/home-{name}.yaml

Output in clusterconfig/home-{name}.yaml is multi-document YAML.

Edit Decision Map

Change type	File to edit
Shared machine config (sysctls, kubelet, features, CRI, NTP)	templates/controlplane.yaml
Shared cluster config (apiServer, etcd, networking)	templates/controlplane.yaml
Per-node: hostname, IP address, VIP, extra interfaces	nodes/{name}.yaml
New Talos system extension service config	New template file + append in Taskfile
New config document (EthernetConfig, KmsgLogConfig, etc.)	New template file + append in Taskfile

Never edit clusterconfig/home-*.yaml directly — it is regenerated by task talos:generate.

Strategic Merge Patch Rules (nodes/{name}.yaml)

Patches in nodes/ are partial v1alpha1 documents — only keys to override.

• Scalars override the base value
• Maps merge recursively
• Lists append, except:
  • cluster.network.podSubnets and cluster.network.serviceSubnets are replaced entirely
• machine.network.interfaces[] merges on matching interface: or deviceSelector: key — a patch entry for eth0 updates the existing eth0 entry, it does not add a second one

Adding a New Config Document

Config documents that are not v1alpha1 (e.g. ExtensionServiceConfig, EthernetConfig, KmsgLogConfig) are separate YAML documents appended after the main config, not nested fields.

1. Create provision/talos/templates/{doc-name}.yaml starting with ---:

---
apiVersion: v1alpha1
kind: ExtensionServiceConfig   # or EthernetConfig, etc.
name: my-extension
# ... fields

2. Add an append line in .taskfiles/talos/Taskfile.yaml generate task:

envsubst < templates/{doc-name}.yaml >> /tmp/talos-patched.yaml

Add it before the mv line. Use envsubst < if the template has ${VAR} tokens, plain cat if not.

After Any Edit

task talos:generate          # re-render clusterconfig/
# inspect clusterconfig/home-mc1.yaml to verify output

task talos:apply N=mc1       # apply without reboot (auto mode)
# or
task talos:apply:restart N=mc1   # apply + reboot (for changes that require it)

Changes requiring a reboot: kernel args, extension installs, install image changes. Changes that apply without reboot: most machine config fields (kubelet, sysctls, network config).