Talos V114 Migration

Migrating Talos config to v1.14 multi-doc format

Talos 1.14 introduces a multi-document configuration model that replaces many fields in the legacy v1alpha1 machine: / cluster: blocks with dedicated document kinds (apiVersion: v1alpha1 + kind: <Kind>). The old fields remain supported for backwards compatibility, but new features and fields are only available in the multi-doc format.

This skill migrates config patches from the old format to the new one. It works for any Talos deployment — topf patch directories, raw talosctl gen config output, or hand-written machine configs.

When to use

Use this skill when the task involves ANY of:

• Migrating Talos config patches from v1.13 (or earlier) to v1.14
• Converting deprecated .machine.* or .cluster.* v1alpha1 fields to multi-doc kinds
• A user asks to "migrate to Talos 1.14 config" or "use the new multi-doc format"
• Reviewing a Talos config for deprecated v1alpha1 fields

Do NOT use this skill for:

• Talos version upgrades that don't involve config format changes
• Writing new config from scratch (use talosctl gen config which already emits multi-doc)
• Non-Talos Kubernetes config

Reference documentation

• Document map (authoritative field → kind mapping): https://docs.siderolabs.com/talos/v1.14/reference/configuration/document-map
• v1alpha1 config reference (legacy fields): https://docs.siderolabs.com/talos/v1.14/reference/configuration/v1alpha1/config
• v1.14.0 release notes (behavior changes): https://github.com/siderolabs/talos/releases/tag/v1.14.0

Each new document kind has its own reference page under https://docs.siderolabs.com/talos/v1.14/reference/configuration/<group>/<kind>/ (for example, kubernetes/kubeletconfig, block/volumeconfig, network/layer2vipconfig). Fetch the page for a kind when you need the exact field names and types.

Workflow

1. Inventory all config files

Read every patch/config file in the target directory (or the single machine config). Record each v1alpha1 field path in use. Common locations for topf: patches/ (global), control-plane/, worker/, node/<hostname>/. For raw talosctl: a single controlplane.yaml / worker.yaml.

2. Classify each field

For every field, look it up in mapping.md (the condensed field-by-field reference built from the document map). Classify it as:

• Deprecated → migrate to the indicated multi-doc kind
• Not deprecated → leave as v1alpha1
• No multi-doc equivalent → flag for manual handling (see Gotchas)

3. Rewrite deprecated fields as multi-doc documents

For each deprecated field, create or update a multi-doc patch file containing the new apiVersion: v1alpha1 + kind: <Kind> document. Move the field value to the new document, renaming fields where the mapping requires it.

Multi-doc files may contain several ----separated documents of different kinds — for example, a single file can hold both VolumeConfig for EPHEMERAL and VolumeConfig for STATE.

4. Keep non-deprecated v1alpha1 fields as-is

Leave fields that are NOT deprecated in their original v1alpha1 form. The two formats coexist in v1.14. See the "NOT deprecated" table in mapping.md for the list.

5. Verify

• Re-read every rewritten file to confirm the YAML is valid and the document kinds/fields match the reference pages.
• If using topf, run topf nodes to confirm the config compiles, then topf apply (with user approval) to push to nodes.
• For raw talosctl, run talosctl apply-config against a single node first.

Gotchas

$patch: delete works on multi-doc maps too

Strategic-merge $patch: delete directives work on both v1alpha1 fields and multi-doc document maps. Use them to remove auto-generated defaults or specific keys:

• Delete an entire auto-generated document (e.g. Flannel):

  ---
  apiVersion: v1alpha1
  kind: KubeFlannelCNIConfig
  $patch: delete

• Delete a specific taint key:

  ---
  apiVersion: v1alpha1
  kind: KubeNodeConfig
  taints:
    node-role.kubernetes.io/control-plane:
      $patch: delete

• Delete a specific label key:

  ---
  apiVersion: v1alpha1
  kind: KubeNodeConfig
  labels:
    node.kubernetes.io/exclude-from-external-load-balancers:
      $patch: delete

KubeFlannelCNIConfig is auto-generated — omitting it is not enough

talosctl gen config emits a KubeFlannelCNIConfig document by default in v1.14. If you use an external CNI (Cilium, Calico, etc.) and had cluster.network.cni.name: none in v1alpha1, simply not including a KubeFlannelCNIConfig patch will NOT disable Flannel — the generated default will still be present in the final config. You must explicitly delete it:

---
apiVersion: v1alpha1
kind: KubeFlannelCNIConfig
$patch: delete