TOPF

https://postfinance.github.io/topf/main/
Admin
TOPF is a single-binary tool for managing the lifecycle of Talos-based Kubernetes clusters,...
Tokens:8,088
Snippets:114
Trust Score:9.7
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install TOPF via Homebrew

Source: https://postfinance.github.io/topf/main/getting-started

Use the Homebrew package manager to install the TOPF binary.

```bash
brew install postfinance/tap/topf
```

--------------------------------

### Complete topf.yaml configuration example

Source: https://postfinance.github.io/topf/main/configuration

A comprehensive example demonstrating all available fields for cluster and node definitions.

```yaml
# Required fields
clusterName: mycluster
clusterEndpoint: https://192.168.1.100:6443
kubernetesVersion: 1.34.1

# Optional: Talos version and schematic for installer image generation
talosVersion: 1.12.7
schematicId: 376567988ad370138ad8b2698212367b8edcb69b5fd68c80be1f2ec7d603b4ba

# Optional: Custom image factory and platform (defaults: factory.talos.dev, metal)
# factory: factory.talos.dev
# platform: metal
# secureboot: false

# Optional: Directory containing patches (default: same directory as topf.yaml)
# patchesDir: .

# Optional: Path to secrets.yaml (default: <dir of topf.yaml>/secrets.yaml)
# Relative paths are resolved against the directory containing topf.yaml.
# secretsPath: secrets.yaml

# Optional: Provider binaries for dynamic configuration
secretsProvider: /path/to/secrets-provider
nodesProvider: /path/to/nodes-provider

# Optional: Arbitrary data for use in patch templates
data:
  region: us-west-2
  environment: production

# Node definitions
nodes:
  - host: node1
    ip: 172.20.10.2
    role: control-plane
    data:
      uuid: "550e8400-e29b-41d4-a716-446655440000"
  - host: node2
    ip: 172.20.10.3
    role: worker
  - host: cloud-node1
    ip: 10.0.1.5
    role: worker
    platform: aws  # per-node platform override
```

--------------------------------

### Install TOPF via Go

Source: https://postfinance.github.io/topf/main/getting-started

Install the latest version of TOPF directly using the Go toolchain.

```bash
go install github.com/postfinance/topf/cmd/topf@latest
```

--------------------------------

### Configure Installer Image via topf.yaml

Source: https://postfinance.github.io/topf/main/commands/upgrade

Set the talosVersion and schematicId in topf.yaml to automatically generate the cluster-level installer image.

```yaml
talosVersion: 1.12.7
schematicId: 376567988ad370138ad8b2698212367b8edcb69b5fd68c80be1f2ec7d603b4ba
```

--------------------------------

### Define Installation Disk Patch

Source: https://postfinance.github.io/topf/main/getting-started

Create a patch file to specify the installation disk for Talos nodes.

```yaml
machine:
  install:
    disk: /dev/vda
```

--------------------------------

### Render command usage examples

Source: https://postfinance.github.io/topf/main/commands/render

Common command-line invocations for generating node configurations with various flags.

```bash
# Render all node configs to ./output
topf render

# Render using the actual running Talos versions
topf render --online

# Render to a custom directory
topf render -o /tmp/configs

# Render only control-plane nodes
topf render --nodes-filter "cp-.*"
```

--------------------------------

### Define a schematic configuration

Source: https://postfinance.github.io/topf/main/configuration

Example of a standard schematic definition file structure.

```yaml
customization:
  systemExtensions:
    officialExtensions:
      - siderolabs/qemu-guest-agent
      - siderolabs/nvidia-container-toolkit

```

--------------------------------

### Example Cluster Directory Structure

Source: https://postfinance.github.io/topf/main/configuration-model

A typical directory layout showing the organization of patches by scope and node.

```text
.
├── all
│   └── 01-installation.yaml
├── control-plane
│   ├── 01-vip.yaml
│   ├── 02-disable-discovery.yaml
│   └── 03-allow-cp-scheduling.yaml
├── worker
│   └── 01-worker-taints.yaml
├── node
│   └── node1
│       └── 01-some-nodespecific-patch.yaml
└── topf.yaml
```

--------------------------------

### Apply Command Usage Examples

Source: https://postfinance.github.io/topf/main/commands/apply

Various ways to invoke the topf apply command for configuration management, previewing changes, and cluster bootstrapping.

```bash
# Apply with confirmation (default)
topf apply

# Apply without confirmation
topf apply --confirm=false

# Preview what would be changed (exits with code 2 if changes are detected)
topf apply --dry-run

# Preview without redacting secrets (e.g. for debugging)
topf apply --dry-run --redact=false

# Apply using a specific mode
topf apply --mode=staged
topf apply --mode=no-reboot

# Apply and bootstrap a new cluster
topf apply --auto-bootstrap

# Apply only to healthy nodes, skip problematic ones
topf apply --skip-problematic-nodes

# Apply without waiting for nodes to stabilize
topf apply --skip-post-apply-checks

# Apply to nodes even if they have unmet conditions
topf apply --allow-not-ready
```

--------------------------------

### Secrets Command Usage Examples

Source: https://postfinance.github.io/topf/main/commands/secrets

Demonstrates outputting secrets to stdout, saving to a file, and generating secrets without interactive confirmation.

```bash
# Output secrets to stdout
topf secrets

# Save secrets to a file
topf secrets > secrets.yaml

# Generate secrets without confirmation (e.g. in CI)
topf secrets --confirm=false
```

--------------------------------

### Reset Command Usage Examples

Source: https://postfinance.github.io/topf/main/commands/reset

Various ways to invoke the reset command, including full disk wipes, graceful resets, and node filtering.

```bash
# Reset with full disk wipe (default)
topf reset

# Reset only STATE and EPHEMERAL partitions
topf reset --full=false

# Graceful reset (drain workloads first)
topf reset --graceful

# Reset and shut down instead of rebooting
topf reset --shutdown

# Reset specific nodes
topf reset --nodes-filter "node[1-2]"

# Reset and wait for nodes to enter maintenance mode (useful for chaining with apply)
topf reset --wait-for-maintenance
```

--------------------------------

### Manual Installer Image Patch

Source: https://postfinance.github.io/topf/main/commands/upgrade

Explicitly define the installer image using a patch file to override default settings.

```yaml
machine:
  install:
    image: factory.talos.dev/metal-installer/376567988ad370138ad8b2698212367b8edcb69b5fd68c80be1f2ec7d603b4ba:v1.12.0
```

--------------------------------

### Secrets Provider Commands

Source: https://postfinance.github.io/topf/main/providers

The secrets provider binary uses get and put subcommands to manage the secrets bundle.

```bash
<binary> secrets get <clusterName>
```

```bash
<binary> secrets put <clusterName>
```

--------------------------------

### Per-node Installer Override

Source: https://postfinance.github.io/topf/main/commands/upgrade

Apply a node-specific patch to upgrade a single node to a different version or schematic.

```yaml
machine:
  install:
    image: factory.talos.dev/metal-installer/376567988ad370138ad8b2698212367b8edcb69b5fd68c80be1f2ec7d603b4ba:v1.13.0
```

--------------------------------

### Filter nodes using regex

Source: https://postfinance.github.io/topf/main/configuration

Examples of using the --nodes-filter flag to target specific nodes or groups of nodes.

```bash
# Target a single node
topf apply --nodes-filter "node1"

# Target nodes 1 through 3
topf apply --nodes-filter "node[1-3]"

# Target all control plane nodes by naming convention
topf reset --nodes-filter "cp-.*"

# Target a specific FQDN
topf upgrade --nodes-filter "node1.company.tld"
```

--------------------------------

### Execute CI/CD pipeline steps for configuration deployment

Source: https://postfinance.github.io/topf/main/production-usage

Clone the versioned configuration repository before executing the topf apply command.

```bash
# Pull versioned configuration
git clone --branch "${CONFIG_REF}" "https://${CONFIG_REPO}" .

# Apply
topf apply --confirm=false
```

--------------------------------

### Apply configuration

Source: https://postfinance.github.io/topf/main/migration-from-talhelper

Compare the talhelper generation workflow with the direct TOPF apply command.

```bash
# Before (talhelper)
talhelper genconfig
talosctl apply-config --nodes 192.168.1.1 --file clusterconfig/mycluster-node-01.yaml

# After (TOPF)
topf apply
```

--------------------------------

### Generate and use kubeconfig

Source: https://postfinance.github.io/topf/main/commands/kubeconfig

Commands to output the kubeconfig to stdout or save it to a file for immediate use with kubectl.

```bash
# Output kubeconfig to stdout
topf kubeconfig

# Save and use immediately
topf kubeconfig > kubeconfig
export KUBECONFIG=$(pwd)/kubeconfig
kubectl get nodes
```

--------------------------------

### Nodes Provider Output Format

Source: https://postfinance.github.io/topf/main/providers

The binary must output a YAML list of nodes to stdout.

```yaml
- host: dynamic-node-01
  ip: 192.168.1.10
  role: worker
  data:
    uuid: "550e8400-e29b-41d4-a716-446655440000"
    rack: "A3"
- host: dynamic-node-02
  ip: 192.168.1.11
  role: worker
  data:
    uuid: "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
    rack: "B1"
```

--------------------------------

### Use Env Function in a Multi-Document Template

Source: https://postfinance.github.io/topf/main/configuration-model

Shows conditional configuration of a registry mirror based on an environment variable.

```yaml
{{ if env "REGISTRY_MIRROR" -}}
apiVersion: v1alpha1
kind: RegistryMirrorConfig
name: ghcr.io
endpoints:
  - url: {{ env "REGISTRY_MIRROR" }}
{{- end }}
```

--------------------------------

### Generate and use talosconfig

Source: https://postfinance.github.io/topf/main/commands/talosconfig

Output the configuration to stdout or save it to a file for use with talosctl.

```bash
# Output talosconfig to stdout
topf talosconfig

# Save and use with talosctl
topf talosconfig > talosconfig
export TALOSCONFIG=$(pwd)/talosconfig
talosctl version
```

--------------------------------

### Upgrade Kubernetes with topf apply

Source: https://postfinance.github.io/topf/main/kubernetes-upgrade

Applies the version change directly to static pod manifests without compatibility validation.

```bash
# Edit topf.yaml: kubernetesVersion: 1.33.0
topf apply
```

--------------------------------

### Define Cluster Configuration

Source: https://postfinance.github.io/topf/main/getting-started

Create a topf.yaml file to specify cluster metadata and node definitions.

```yaml
kubernetesVersion: 1.35.5
talosVersion: 1.13.4
clusterEndpoint: https://192.168.1.100:6443
clusterName: mycluster

nodes:
  - host: node1
    ip: 192.168.1.100
    role: control-plane
```

--------------------------------

### Migrate secrets and templating

Source: https://postfinance.github.io/topf/main/migration-from-talhelper

Transition from envsubst and external secret files to SOPS-encrypted fields and Go templates.

```yaml
# talenv.sops.yaml
CONTROLPLANE_ENDPOINT: ENC[AES256_GCM,data:...,type:str]

# talconfig.yaml
additionalApiServerCertSans:
  - "${CONTROLPLANE_ENDPOINT}"
```

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

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

--------------------------------

### Translate talconfig.yaml to topf.yaml

Source: https://postfinance.github.io/topf/main/migration-from-talhelper

Convert node definitions from talhelper format to the simplified TOPF structure.

```yaml
clusterName: mycluster
endpoint: https://192.168.1.100:6443
kubernetesVersion: v1.32.8
nodes:
  - hostname: node-01
    ipAddress: 192.168.1.1
    installDisk: /dev/nvme0n1
    controlPlane: true
    networkInterfaces:
      - interface: eno1
        dhcp: true
        vip:
          ip: 192.168.1.100
  - hostname: node-02
    ipAddress: 192.168.1.2
    controlPlane: false
```

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

--------------------------------

### Define a templated schematic configuration

Source: https://postfinance.github.io/topf/main/configuration

Use Go templates within a .yaml.tpl file to dynamically include extensions based on node roles.

```yaml
customization:
  systemExtensions:
    officialExtensions:
      - siderolabs/qemu-guest-agent
      {{- if eq .Node.Role "worker" }}
      - siderolabs/nvidia-container-toolkit
      {{- end }}

```

--------------------------------

### Execute clusterinfo command

Source: https://postfinance.github.io/topf/main/commands/clusterinfo

Run this command in the terminal to output cluster configuration details in YAML format.

```bash
topf clusterinfo
```

--------------------------------

### Reference a schematic definition file

Source: https://postfinance.github.io/topf/main/configuration

Use the @ prefix in the schematicId field to point to a local schematic definition file.

```yaml
schematicId: @schematic.yaml

```

--------------------------------

### Nodes Provider Binary Execution

Source: https://postfinance.github.io/topf/main/providers

The binary is invoked with the cluster name as an argument to fetch node definitions.

```bash
<binary> nodes <clusterName>
```

--------------------------------

### Upgrade Kubernetes with talosctl

Source: https://postfinance.github.io/topf/main/kubernetes-upgrade

Performs an orchestrated upgrade including compatibility checks and component rollouts.

```bash
talosctl upgrade-k8s --to 1.33.0
```

--------------------------------

### Nodes Provider Configuration

Source: https://postfinance.github.io/topf/main/providers

Configure the nodes provider path in the topf.yaml file.

```yaml
# topf.yaml
nodesProvider: /path/to/nodes-provider
nodes:
  - host: static-node-01
    ip: 192.168.1.1
    role: control-plane
```

--------------------------------

### List nodes in table and YAML formats

Source: https://postfinance.github.io/topf/main/commands/nodes

Use the nodes command to retrieve node information. The output format can be toggled between table and YAML using the -o flag.

```bash
# List nodes in table format
topf nodes

# List nodes in YAML format
topf nodes -o yaml
```

--------------------------------

### Pull TOPF Container Image

Source: https://postfinance.github.io/topf/main/getting-started

Download the official TOPF container image from the GitHub Container Registry.

```bash
docker pull ghcr.io/postfinance/topf
```

--------------------------------

### Extract patches into files

Source: https://postfinance.github.io/topf/main/migration-from-talhelper

Move inline patches into structured directory-based files.

```yaml
patches:
  - |-
    cluster:
      proxy:
        disabled: true
      discovery:
        enabled: true
controlPlane:
  patches:
    - |-
      ...
```

```text
all/01-cluster-config.yaml              # global patches
control-plane/01-vip.yaml              # control-plane patches
worker/10-kubelet.yaml                 # worker patches
node/node-01/01-specific.yaml          # node-specific patches
```

```yaml
# all/01-cluster-config.yaml
cluster:
  proxy:
    disabled: true
  discovery:
    enabled: true
```

--------------------------------

### Upgrade command variations

Source: https://postfinance.github.io/topf/main/commands/upgrade

Various flags available for the topf upgrade command to control node upgrade behavior, concurrency, and staging.

```bash
# Upgrade with confirmation (default)
topf upgrade

# Upgrade without confirmation
topf upgrade --confirm=false

# Preview what would be upgraded
topf upgrade --dry-run

# Upgrade without draining the Kubernetes node
topf upgrade --drain=false

# Upgrade up to 3 worker nodes concurrently
topf upgrade --max-parallel=3

# Upgrade with a custom drain timeout
topf upgrade --drain-timeout=10m

# Force upgrade on legacy (Talos < 1.13) nodes, skipping etcd health checks
topf upgrade --force

# Upgrade, falling back to pod deletion if graceful drain fails
topf upgrade --delete-if-eviction-fails

# Upgrade with a longer drain timeout (shared by graceful and fallback)
topf upgrade --delete-if-eviction-fails --drain-timeout=10m

# Stage an upgrade without rebooting (reboot manually later to complete it)
topf upgrade --stage

# Stage an upgrade and label the node so a controller can find it
topf upgrade --stage --stage-label topf.postfinance.ch/staged-upgrade=true

# Stage an upgrade and taint the node to discourage new pods from scheduling
topf upgrade --stage --stage-taint topf.postfinance.ch/staged-upgrade=true:PreferNoSchedule

# Stage an upgrade and annotate the node so a controller can find it
topf upgrade --stage --stage-annotation topf.postfinance.ch/staged-at=2026-08-07
```

--------------------------------

### Define versioned configuration in topf.yaml

Source: https://postfinance.github.io/topf/main/production-usage

Use the data field to store metadata about external configuration sources, such as Git repository locations and references.

```yaml
# topf.yaml
clusterName: prod-cluster-01
clusterEndpoint: https://10.0.0.100:6443
kubernetesVersion: 1.32.8

nodesProvider: custom-binary
secretsProvider: custom-binary

data:
  configSource:
    repo: git.company.tld/kubernetes/talos/config
    ref: main

nodes:
  - host: cp-01
    ip: 10.0.0.1
    role: control-plane
```

--------------------------------

### Secrets Provider Configuration

Source: https://postfinance.github.io/topf/main/providers

Configure the secrets provider path in the topf.yaml file.

```yaml
# topf.yaml
secretsProvider: /path/to/secrets-provider
```

--------------------------------

### Check schematic registration status

Source: https://postfinance.github.io/topf/main/configuration

Verify if a schematic ID is already registered with the image factory using curl.

```bash
curl https://factory.talos.dev/schematics/<id>

```

--------------------------------

### Set node filter via environment variable

Source: https://postfinance.github.io/topf/main/configuration

Configuring the node filter using the TOPF_NODES_FILTER environment variable instead of a flag.

```bash
export TOPF_NODES_FILTER="node[1-3]"
topf apply
```

--------------------------------

### Use Per-Node Data in a Patch

Source: https://postfinance.github.io/topf/main/configuration-model

Demonstrates accessing node-specific data defined in the configuration within a template.

```yaml
machine:
  kubelet:
    extraArgs:
      provider-id: {{ .Node.Data.uuid }}
```

--------------------------------

### Configure Node Hostname

Source: https://postfinance.github.io/topf/main/getting-started

Use a template patch to set the node hostname based on the configuration host value.

```yaml
apiVersion: v1alpha1
kind: HostnameConfig
auto: "off"
hostname: {{ .Node.Host }}
```

--------------------------------

### Migrate JSON patches to strategic merge

Source: https://postfinance.github.io/topf/main/migration-from-talhelper

Replace RFC 6902 JSON patches with strategic merge patches using $patch: delete.

```yaml
- op: remove
  path: /machine/nodeLabels/node.kubernetes.io~1exclude-from-external-load-balancers
```

```yaml
# control-plane/04-remove-external-lb-exclusion.yaml
machine:
  nodeLabels:
    node.kubernetes.io/exclude-from-external-load-balancers:
      $patch: delete
```

--------------------------------

### Update topf.yaml configuration

Source: https://postfinance.github.io/topf/main/kubernetes-upgrade

Updates the configuration file to reflect the new Kubernetes version after an upgrade.

```yaml
kubernetesVersion: 1.33.0
```

--------------------------------

### Disable output redaction

Source: https://postfinance.github.io/topf/main/configuration

Disabling the redaction of sensitive information for debugging purposes.

```bash
topf apply --dry-run --redact=false
```
Tokens:
Raw