Migrate Talhelper To Topf

Migrating from talhelper to TOPF

talhelper is archived (since Aug 2026). TOPF is a recommended successor and the upstream migration guide is canonical: https://postfinance.github.io/topf/main/migration-from-talhelper/

Critical: migrate on the running config format, upgrade later

Do the tooling migration on whatever Talos version and config format the cluster runs today, and prove the TOPF render is equivalent to talhelper's (Step 8) before the first topf apply. Only then upgrade Talos or move to the v1.14 multi-document format, as a separate change with the talos-v114-migration skill. Mixing the two makes the first diff unreviewable: every hunk could be the tool or the format.

TOPF v0.6.0+ renders v1.14 multi-document configs too; that is not a reason to switch formats during the migration. The examples below use the v1.13 single-document machine: / cluster: format.

When to use

Use this skill when the task involves ANY of:

• Migrating a cluster managed by talhelper to TOPF
• Converting talconfig.yaml to topf.yaml + patch files
• A user asks to "migrate to topf", "switch from talhelper", or "move off talhelper"
• Handling talenv.sops.yaml / talsecret.sops.yaml as part of a topf migration

Do NOT use this skill for:

• The Talos v1.14 multi-doc config format migration (use talos-v114-migration)
• Writing a topf config from scratch with no existing talhelper setup
• Talos version upgrades that don't involve a tooling migration

How talhelper and TOPF differ

Reference documentation

• Upstream migration guide: https://postfinance.github.io/topf/main/migration-from-talhelper/
• TOPF configuration reference: https://postfinance.github.io/topf/main/configuration/
• TOPF configuration model (templating, secret resolution): https://postfinance.github.io/topf/main/configuration-model/
• talhelper config reference (archived): https://budimanjojo.github.io/talhelper/latest/reference/configuration/
• Full talhelper → topf field mapping: see field-mapping.md in this skill directory.

Workflow

Work through the user's talconfig.yaml in this order. Always read the actual talconfig.yaml (and talenv.sops.yaml / talsecret.sops.yaml if present) in the repo before editing — do not guess at field names.

1. Inventory the talhelper setup

Read talconfig.yaml and record:

• Top-level cluster fields (clusterName, endpoint, talosVersion, kubernetesVersion, domain, allowSchedulingOnMasters, etc.)
• Top-level patches:, controlPlane: block, worker: block, inlineManifests:
• Per-node fields (every key under each nodes: entry)
• Whether talenv.sops.yaml / talenv.yaml exists and what keys it holds
• Whether talsecret.sops.yaml / talsecret.yaml exists

2. Create topf.yaml

Translate the top-level cluster fields and the node list. Only these fields have direct equivalents in topf.yaml; everything else becomes a patch (Step 3).

Example minimal topf.yaml:

clusterName: mycluster
clusterEndpoint: https://192.168.1.100:6443
kubernetesVersion: v1.32.8
talosVersion: v1.12.0
nodes:
  - host: node-01
    ip: 192.168.1.1
    role: control-plane
  - host: node-02
    ip: 192.168.1.2
    role: worker

For the full field map (including fields with no direct equivalent), see field-mapping.md.

3. Extract node config into patch files

Patches live in a directory tree next to topf.yaml (default: same dir; override with patchesDir). TOPF loads, in order, for each node:

<patchesDir>/all/             # applied to every node
<patchesDir>/control-plane/   # applied to control-plane nodes only
<patchesDir>/worker/          # applied to worker nodes only
<patchesDir>/node/<host>/     # applied to one specific node

Files are matched by *.yaml, *.yml, or *.tpl (templated). They are applied in lexicographic order within each folder, so prefix with two-digit numbers to control ordering (01-…, 02-…). Lists with a merge key (cluster.inlineManifests by name, machine.files by path) merge across scopes exactly as they did in talhelper — both tools use Talos's own strategic-merge patcher — so a control-plane/ patch that adds inline manifests appends to the all/ list instead of replacing it.

Map each talhelper source to a target directory:

Each patch file is a single standalone YAML document — a strategic merge patch against the Talos v1.13 machine config (machine: / cluster: maps).

Example per-node install + network patches:

# node/node-01/01-install.yaml
machine:
  install:
    disk: /dev/nvme0n1

# node/node-01/02-network.yaml
machine:
  network:
    interfaces:
      - interface: eno1
        dhcp: true

For a control-plane VIP shared by all CP nodes, put it under control-plane/:

# control-plane/01-vip.yaml
machine:
  network:
    interfaces:
      - interface: eno1
        vip:
          ip: 192.168.1.100

4. Convert JSON patches to strategic merge

talhelper accepts RFC 6902 JSON patches (arrays of {op, path, value}). TOPF does not — it only accepts strategic merge patches, and will reject a document that is a YAML array with an error like "document at index N looks like a JSON patch (array of operations), which is not supported".

Remove a field (e.g. a node label):

# Before (RFC 6902)
- op: remove
  path: /machine/nodeLabels/node.kubernetes.io~1exclude-from-external-load-balancers

# After (strategic merge, $patch: delete)
machine:
  nodeLabels:
    node.kubernetes.io/exclude-from-external-load-balancers:
      $patch: delete

Note / in keys is written literally — no ~1 escaping.

Add/replace a field: write the strategic merge directly:

# Before
- op: add
  path: /machine/kubelet/extraArgs/rotate-server-certificates
  value: "true"

# After
machine:
  kubelet:
    extraArgs:
      rotate-server-certificates: "true"

If a talhelper patch was already strategic merge (a mapping, not an array), it carries over unchanged — just move it into the right file.

5. Migrate envsubst / talenv to Go templates

talhelper reads talenv.sops.yaml (or talenv.yaml) into env vars and runs envsubst on talconfig.yaml and patch files. TOPF has no envsubst.

Pattern A — non-secret values: move them under data: in topf.yaml:

# topf.yaml
data:
  controlPlaneEndpoint: 192.168.1.100
  domain: mycluster.local

# control-plane/01-extra-SANs.yaml.tpl
cluster:
  apiServer:
    certSANs:
      - {{ .Data.controlPlaneEndpoint }}

The .tpl suffix triggers Go template rendering. Templates use the sprig function library and missingkey=error (a missing key is a hard error, not a blank).

Pattern B — secret values: put them under data: in topf.yaml and encrypt the whole topf.yaml with SOPS (or use vals references like ref+vault://…). SOPS-encrypted values in topf.yaml are decrypted at load time and redacted from output by default.

# topf.yaml (SOPS-encrypted)
data:
  controlPlaneEndpoint: ENC[AES256_GCM,data:...,type:str]

Template files reference them the same way: {{ .Data.controlPlaneEndpoint }}.

Encrypt only the data block so the rest of topf.yaml stays diffable and editable without sops, and move the values without ever writing plaintext to disk:

# .sops.yaml — first matching rule wins, so list this before any catch-all
creation_rules:
  - path_regex: topf\.yaml$
    encrypted_regex: ^data$
    mac_only_encrypted: true
    age: <recipient>

# placeholders in data:, then encrypt in place, then overwrite each value from talenv
sops encrypt -i topf.yaml
sops set topf.yaml '["data"]["repoToken"]' "\"$(sops -d --extract '["REPO_TOKEN"]' talenv.sops.yaml)\""
sops filestatus topf.yaml    # {"encrypted":true}

A .tpl file is parsed by Go's template engine in full, YAML comments included — a literal {{ in a comment fails the render with bad character or function not defined. Values with characters YAML could misread are safer as {{ .Data.x | quote }}.

Per-node data: a node's data: block is reachable in templates as .Node.Data.<key> (the node the patch is being rendered for). Use this for per-node values that used to be envsubst'd with node-specific vars.

talhelper template variables like {{ .MachineConfig … }} do not exist in TOPF. Replace with the TOPF template context:

6. Rename the secrets bundle

talsecret.sops.yaml (or talsecret.yaml) → secrets.yaml. The Talos secrets bundle format is identical between talhelper and TOPF; only the filename changes. TOPF looks for secrets.yaml next to topf.yaml by default (override with secretsPath). Keep it SOPS-encrypted.

git mv talsecret.sops.yaml secrets.yaml

Delete talenv.sops.yaml / talenv.yaml — there is no equivalent in TOPF. Its contents either become data: in topf.yaml (if still needed) or are dropped. Also delete clusterconfig/ and its .gitignore entries (talenv.yaml, talsecret.yaml); add output/ instead — that is where topf render writes full configs, secrets included.

7. Apply

# Before (talhelper)
talhelper genconfig
talosctl apply-config --insecure -n 192.168.1.1 --file clusterconfig/mycluster-node-01.yaml
# ...repeat per node

# After (TOPF) — single command, all nodes
topf apply

For an existing cluster being migrated (nodes already running Talos), use --dry-run first to diff the generated config against the running nodes and confirm nothing unexpected changes:

topf apply --dry-run
topf apply

topf apply generates the machine config from patches + secrets and applies it to each node over the Talos API (not --insecure file apply). It authenticates with a client certificate minted from secrets.yaml, so the talhelper-era talosconfig keeps working too (same secrets bundle, same CA); topf talosconfig regenerates it if needed.

TOPF dials every node's ip (or host) on :50000 directly. There is no talosctl -e <control-plane> -n <worker> style apid proxying, so a NAT'd or LAN-only node is only reachable when TOPF runs from a network that reaches it. Use --nodes-filter to apply the reachable nodes from elsewhere.