Skip to main content

​
Overview

Configuration commands handle both machine configurations (for Talos nodes) and client configurations (talosconfig). These commands allow you to generate, apply, and manage configurations.

​
gen config

Generate a set of configuration files for a Talos cluster. 
talosctl gen config <cluster-name> <cluster-endpoint> [flags]

​
Description

Generates machine configurations for control plane and worker nodes, along with a talosconfig file for cluster access. The cluster endpoint is the URL for the Kubernetes API server.

​
Arguments

​
cluster-name
string
required
Name of the cluster
​
cluster-endpoint
string
required
The Kubernetes API endpoint URL (e.g., https://10.5.0.1:6443)For a single control plane node, use port 6443. For HA setups with a load balancer, use the load balancer IP and port.

​
Flags

​
--output
string
Destination for generated files
  • When multiple output types: must be a directory
  • For single output type: can be a file path or - for stdout
  • If not specified: uses current working directory
Short flag: -oExample:
talosctl gen config my-cluster https://10.5.0.1:6443 -o ./configs
​
--output-types
string[]
default:"controlplane,worker,talosconfig"
Types of outputs to generateOptions: controlplane, worker, talosconfigShort flag: -tExample:
talosctl gen config my-cluster https://10.5.0.1:6443 -t controlplane,talosconfig
​
--install-disk
string
default:"/dev/sda"
The disk to install Talos onExample:
talosctl gen config my-cluster https://10.5.0.1:6443 --install-disk /dev/nvme0n1
​
--install-image
string
The container image used to perform installationDefault: Latest Talos installer imageExample:
talosctl gen config my-cluster https://10.5.0.1:6443 \
  --install-image ghcr.io/siderolabs/installer:v1.8.0
​
--kubernetes-version
string
Desired Kubernetes version to runDefault: Latest supported versionExample:
talosctl gen config my-cluster https://10.5.0.1:6443 --kubernetes-version 1.31.0
​
--additional-sans
string[]
Additional Subject Alternative Names for the API server certificateExample:
talosctl gen config my-cluster https://10.5.0.1:6443 \
  --additional-sans api.example.com,10.5.0.10
​
--dns-domain
string
default:"cluster.local"
The DNS domain to use for the clusterExample:
talosctl gen config my-cluster https://10.5.0.1:6443 --dns-domain k8s.local
​
--config-patch
string[]
Patch generated machine configs (applied to all node types)Use @file to read a patch from file.Example:
talosctl gen config my-cluster https://10.5.0.1:6443 \
  --config-patch @patch.yaml
​
--config-patch-control-plane
string[]
Patch generated machine configs (applied to init and controlplane types)Example:
talosctl gen config my-cluster https://10.5.0.1:6443 \
  --config-patch-control-plane @cp-patch.yaml
​
--config-patch-worker
string[]
Patch generated machine configs (applied to worker type)Example:
talosctl gen config my-cluster https://10.5.0.1:6443 \
  --config-patch-worker @worker-patch.yaml
​
--with-docs
boolean
default:"true"
Render machine configs with documentation for each fieldExample:
talosctl gen config my-cluster https://10.5.0.1:6443 --with-docs=false
​
--with-examples
boolean
default:"true"
Render machine configs with commented examplesExample:
talosctl gen config my-cluster https://10.5.0.1:6443 --with-examples=false
​
--with-cluster-discovery
boolean
default:"true"
Enable cluster discovery featureExample:
talosctl gen config my-cluster https://10.5.0.1:6443 --with-cluster-discovery=false
​
--with-kubespan
boolean
default:"false"
Enable KubeSpan featureExample:
talosctl gen config my-cluster https://10.5.0.1:6443 --with-kubespan
​
--with-secrets
string
Use a secrets file generated using talosctl gen secretsExample:
talosctl gen config my-cluster https://10.5.0.1:6443 --with-secrets secrets.yaml
​
--talos-version
string
The desired Talos version to generate config for (backwards compatibility)Example:
talosctl gen config my-cluster https://10.5.0.1:6443 --talos-version v1.7.0
​
--registry-mirror
string[]
List of registry mirrors in format: <registry>=<mirror-url>Example:
talosctl gen config my-cluster https://10.5.0.1:6443 \
  --registry-mirror docker.io=https://registry.local

​
Examples

Generate basic configuration 
talosctl gen config my-cluster https://10.5.0.1:6443
Output: 
Created controlplane.yaml
Created worker.yaml
Created talosconfig
Generate with custom install disk 
talosctl gen config my-cluster https://10.5.0.1:6443 \
  --install-disk /dev/nvme0n1
Generate with specific Kubernetes version 
talosctl gen config my-cluster https://10.5.0.1:6443 \
  --kubernetes-version 1.30.0
Generate with additional SANs 
talosctl gen config my-cluster https://api.example.com:6443 \
  --additional-sans api.example.com,api-internal.example.com,10.5.0.10
Generate control plane config only 
talosctl gen config my-cluster https://10.5.0.1:6443 \
  -t controlplane \
  -o controlplane.yaml
Generate with config patches 
talosctl gen config my-cluster https://10.5.0.1:6443 \
  --config-patch-control-plane @cp-patch.yaml \
  --config-patch-worker @worker-patch.yaml
Generate minimal config without docs/examples 
talosctl gen config my-cluster https://10.5.0.1:6443 \
  --with-docs=false \
  --with-examples=false

​
apply-config

Apply a new configuration to a Talos node. 
talosctl apply-config [flags]

​
Description

Applies machine configuration to one or more nodes. The configuration can be applied in different modes and can be patched on-the-fly.

​
Flags

​
--file
string
required
The filename of the configuration to applyShort flag: -fExample:
talosctl apply-config -n 10.5.0.2 -f controlplane.yaml
​
--mode
string
default:"auto"
Apply configuration modeOptions:
  • auto - Automatically determine the mode
  • no-reboot - Apply without rebooting
  • reboot - Reboot after applying
  • staged - Stage for next reboot
  • try - Try the config with automatic rollback
Short flag: -mExample:
talosctl apply-config -n 10.5.0.2 -f worker.yaml --mode no-reboot
​
--insecure
boolean
default:"false"
Apply config using the insecure (encrypted with no auth) maintenance serviceShort flag: -iExample:
talosctl apply-config -n 10.5.0.2 -f worker.yaml --insecure
​
--dry-run
boolean
default:"false"
Check how the config change will be applied in dry-run modeExample:
talosctl apply-config -n 10.5.0.2 -f worker.yaml --dry-run
​
--config-patch
string[]
List of config patches to apply to the local config file before sendingShort flag: -pExample:
talosctl apply-config -n 10.5.0.2 -f worker.yaml -p @patch.yaml
​
--cert-fingerprint
string[]
List of server certificate fingerprints to accept (for insecure mode)Example:
talosctl apply-config -n 10.5.0.2 -f worker.yaml \
  --insecure \
  --cert-fingerprint xA3mVkKL....
​
--timeout
duration
default:"1m"
Config will be rolled back after specified timeout (if try mode is selected)Example:
talosctl apply-config -n 10.5.0.2 -f worker.yaml --mode try --timeout 5m

​
Examples

Apply configuration to a node 
talosctl apply-config -n 10.5.0.2 -f controlplane.yaml
Apply in maintenance/insecure mode 
talosctl apply-config -n 10.5.0.2 -f worker.yaml --insecure
Dry run to preview changes 
talosctl apply-config -n 10.5.0.2 -f controlplane.yaml --dry-run
Apply without rebooting 
talosctl apply-config -n 10.5.0.2 -f worker.yaml --mode no-reboot
Try mode with automatic rollback 
talosctl apply-config -n 10.5.0.2 -f worker.yaml --mode try --timeout 5m
Apply with inline patch 
talosctl apply-config -n 10.5.0.2 -f worker.yaml \
  -p '[{"op": "add", "path": "/machine/kubelet/extraArgs", "value": {"rotate-server-certificates": "true"}}]'
Output: 
mode: Auto
 * Applied configuration without a reboot

​
config

Manage the client configuration file (talosconfig). 
talosctl config <subcommand> [flags]

​
Subcommands

​
config endpoint

Set the endpoint(s) for the current context. 
talosctl config endpoint <endpoint>... [flags]
Example: 
talosctl config endpoint 10.5.0.1 10.5.0.2

​
config node

Set the node(s) for the current context. 
talosctl config node <node>... [flags]
Example: 
talosctl config node 10.5.0.2 10.5.0.3

​
config context

Set the current context. 
talosctl config context <context> [flags]
Example: 
talosctl config context production

​
config contexts

List all defined contexts. 
talosctl config contexts
Example Output: 
CURRENT  NAME        ENDPOINTS            NODES
*        production  10.5.0.1,10.5.0.2    10.5.0.2,10.5.0.3,10.5.0.4
         staging     10.6.0.1             10.6.0.2,10.6.0.3

​
config add

Add a new context to the talosconfig. 
talosctl config add <context> [flags]
Flags:
​
--ca
string
Path to the CA certificate
​
--crt
string
Path to the certificate
​
--key
string
Path to the key (required if —crt is specified)
Example: 
talosctl config add production \
  --ca ca.crt \
  --crt client.crt \
  --key client.key

​
config remove

Remove context(s) from the talosconfig. 
talosctl config remove <context> [flags]
Flags:
​
--noconfirm
boolean
default:"false"
Do not ask for confirmationShort flag: -y
​
--dry-run
boolean
default:"false"
Dry run mode
Example: 
talosctl config remove old-cluster -y

​
config merge

Merge additional contexts from another talosconfig file. 
talosctl config merge <from> [flags]
Example: 
talosctl config merge ./other-talosconfig

​
config new

Generate a new client configuration file. 
talosctl config new [<path>] [flags]
Flags:
​
--roles
string[]
default:"os:admin"
Roles for the generated certificateExample:
talosctl config new ./new-config --roles os:reader
​
--crt-ttl
duration
default:"87600h"
Certificate TTLExample:
talosctl config new ./new-config --crt-ttl 8760h
Example: 
talosctl -n 10.5.0.2 config new ./operator-config --roles os:operator

​
config info

Show information about the current context. 
talosctl config info [flags]
Flags:
​
--output
string
default:"text"
Output format (text, json, yaml)Short flag: -o
Example: 
talosctl config info
Output: 
Current context:     production
Nodes:               10.5.0.2, 10.5.0.3, 10.5.0.4
Endpoints:           10.5.0.1, 10.5.0.2
Roles:               os:admin
Certificate expires: 9 years from now (2033-01-15)

​
Common Workflows

​
Initial Cluster Setup

Generate configurations 
talosctl gen config my-cluster https://10.5.0.1:6443 \
  --output ./configs \
  --install-disk /dev/sda \
  --additional-sans 10.5.0.1,api.example.com
Apply to first control plane node (maintenance mode) 
talosctl apply-config \
  --nodes 10.5.0.2 \
  --file ./configs/controlplane.yaml \
  --insecure
Configure talosconfig 
export TALOSCONFIG=./configs/talosconfig
talosctl config endpoint 10.5.0.2
talosctl config node 10.5.0.2
Bootstrap etcd 
talosctl bootstrap

​
Configuration Updates

Test configuration change with dry-run 
talosctl apply-config -n 10.5.0.2 -f updated-config.yaml --dry-run
Apply with try mode (automatic rollback) 
talosctl apply-config -n 10.5.0.2 -f updated-config.yaml --mode try --timeout 5m
Apply configuration patch 
talosctl apply-config -n 10.5.0.2 -f controlplane.yaml -p @patch.yaml

​
Managing Multiple Clusters

Add new cluster context 
talosctl config add staging --ca ca.crt --crt client.crt --key client.key
talosctl config endpoint 10.6.0.1
talosctl config node 10.6.0.2 10.6.0.3
Switch between clusters 
talosctl config context staging
talosctl version

talosctl config context production  
talosctl version
List all contexts 
talosctl config contexts

​
Generate Configurations with Patches

Create patch file (patch.yaml) 
machine:
  kubelet:
    extraArgs:
      rotate-server-certificates: "true"
  time:
    servers:
      - time.cloudflare.com
Generate with patch 
talosctl gen config my-cluster https://10.5.0.1:6443 \
  --config-patch @patch.yaml

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us