Talosctl

talosctl — CLI Operations

For machine config YAML (documents, patching) see talosconfig. For Terraform provider see talos-terraform.

⚠️ Configuration Changes Require Dry-Run + Verification

Every apply-config and patch machineconfig MUST be dry-run first, and the user MUST review/approve the output before anything is applied:

# Dry-run first — always
talosctl patch machineconfig --nodes <ip> --patch @patch.yaml --dry-run
talosctl apply-config --nodes <ip> --file config.yaml --dry-run

Only after the user explicitly confirms the dry-run output, run without --dry-run.

⚠️ apply-config Needs the FULL Config File

talosctl apply-config --file <config> replaces the node's entire machine configuration with the contents of <config>. It is NOT a patch tool — providing a partial YAML wipes all unspecified settings.

• Full-file changes (install, network rewrite, secrets rotation) → talosctl apply-config --file <full-config.yaml>
• Targeted changes (one field) → talosctl patch machineconfig --patch @patch.yaml
• Get the current full config first: talosctl get machineconfig v1alpha1 -o yaml

CLI Quick Reference

Cluster Lifecycle

Maintenance

Config Changes

Patch flags: -p, --patch stringArray (inline or @file), --patch-file. Apply modes: -m, --mode auto|no-reboot|reboot|staged|try.

Node-Level Diagnosis

Extensive per-node troubleshooting. Add --nodes <ip> to every command (or -n for multiple).

Services & Logs

talosctl service                       # all services + state
talosctl service <id>                  # single service status
talosctl service <id> start|stop|restart
talosctl logs <service> --tail 100     # service logs (kubelet, etcd, containerd, etc.)
talosctl logs <service> -f             # follow logs
talosctl restart <id>                  # restart a process (e.g. kubelet)
talosctl dmesg                         # kernel logs
talosctl dmesg -f                      # follow kernel logs

Complete Resource Reference (v1.13.7 registry)

talosctl get <type> is the primary read API — Talos models ALL system state as resources. All 167 types (165 machinery + 2 COSI meta) below. Full names are <Name>.<suffix>; aliases are interchangeable. Not every type populates on every node: control-plane types (etcd, secrets, k8s controlplane ns) only on CP nodes, kubespan only when enabled, secrets/* are sensitive (talosctl redacts). This list is version-bound — run talosctl get rd to discover types added by extensions.

talosctl get rd                        # list ALL available resource types on this node
talosctl get <type> -o yaml            # full spec for any resource
talosctl get <type> <id>               # single resource by ID
talosctl get <type> -w                 # watch changes

Common shortcuts: mc/machineconfig, rd, links, routes, addresses, resolvers, hostname, disks, cpu, members, services/svc, nodename, timestatus, mounts.

meta (available on every node)

block / storage (ns runtime)

cluster (ns cluster)

config (ns config)

cri (ns cri)

etcd (ns etcd)

files (ns files)

hardware (ns hardware)

k8s node-local (ns k8s)

k8s control plane (ns controlplane)

kubeaccess (ns config)

kubespan

network (ns network)

perf (ns perf)

runtime (ns runtime)

secrets (ns secrets, control-plane, sensitive)

security (ns security)

siderolink (ns config)

time (ns runtime)

v1alpha1 (ns runtime)

System Inspection

Network Diagnosis

talosctl netstat -t --listening        # TCP listening sockets (host)
talosctl netstat -a                    # all socket states
talosctl netstat -k                    # sockets used by K8s pods
talosctl netstat <namespace>/<pod>     # specific pod's connections
talosctl pcap -i eth0                  # live packet capture (tcpdump alias)
talosctl pcap -i eth0 --output file.pcap

Diagnostics & Debug

etcd

Apply Modes

Reboot Modes

Common Patterns

Bootstrap cluster

talosctl gen secrets --output-file secrets.yaml
talosctl gen config prod https://10.0.1.100:6443 \
  --with-secrets secrets.yaml \
  --config-patch-control-plane @network.yaml
talosctl apply-config --nodes 10.0.1.10 --file controlplane.yaml --insecure
talosctl bootstrap --nodes 10.0.1.10
talosctl apply-config --nodes 10.0.1.11 --file controlplane.yaml
talosctl kubeconfig --nodes 10.0.1.10
kubectl get nodes

Upgrade (rolling CP)

# Sequential CP upgrade with verification
for node in cp1 cp2 cp3; do
  talosctl upgrade --nodes $node --image ghcr.io/siderolabs/installer:v1.13.8
  kubectl wait --for=condition=Ready node/$node --timeout=10m
  talosctl etcd members
  sleep 30
done

Targeted config patch (dry-run first!)

# 1. Dry-run — show what changes WITHOUT applying
talosctl patch machineconfig --nodes cp1 --patch @patch.yaml --dry-run

# 2. After user confirms the diff, apply
talosctl patch machineconfig --nodes cp1 --patch @patch.yaml

Full config replacement (dry-run first!)

# 1. Get current full config
talosctl get machineconfig v1alpha1 --nodes cp1 -o yaml > current.yaml

# 2. Edit, then dry-run the new full config
talosctl apply-config --nodes cp1 --file edited.yaml --dry-run

# 3. After user confirms, apply
talosctl apply-config --nodes cp1 --file edited.yaml

Upgrade Kubernetes

talosctl upgrade-k8s --to v1.36.2 --dry-run
talosctl upgrade-k8s --to v1.36.2

Node troubleshooting workflow

# 1. Services health
talosctl service --nodes <ip>

# 2. Failed service logs
talosctl logs <failing-service> --tail 100 --nodes <ip>

# 3. Kernel issues
talosctl dmesg --nodes <ip>

# 4. Resources (disk/CPU/mem)
talosctl memory --nodes <ip>
talosctl stats --nodes <ip>
talosctl get disks --nodes <ip>           # hardware disk inventory
talosctl get blockdevices --nodes <ip>    # block devices + partitions
talosctl get disks sda -o yaml --nodes <ip>  # single disk detail
talosctl usage /var --nodes <ip>          # filesystem-level usage

# 5. Network
talosctl get links --nodes <ip>
talosctl netstat -t --listening --nodes <ip>

# 6. Full archive for support
talosctl support --nodes <ip>

etcd maintenance

talosctl etcd snapshot /backup/etcd-$(date +%Y%m%d).snapshot
talosctl etcd defrag --nodes cp1
talosctl etcd alarm list
talosctl etcd alarm disarm       # Clear no-space alarms
talosctl etcd forfeit-leadership # Move leader for maintenance

Common Mistakes

• Bootstrap more than once — Only one talosctl bootstrap per cluster lifetime. Running it again creates split-brain.
• Losing secrets — Always --with-secrets secrets.yaml during gen config. Without secrets, you cannot add nodes, rotate certs, or recover. Store encrypted in Vault/SOPS.
• Upgrade all CP simultaneously — Sequential only. etcd needs quorum. One node at a time, verify health between each.
• talosctl apply-config with a partial file — apply-config REPLACES the whole config. Partial YAML wipes unspecified settings. Use talosctl patch machineconfig for targeted changes.
• Skipping --dry-run — Every config change must be dry-run first and reviewed by the user before applying.
• talosctl get disks vs talosctl disks — get disks uses the disks.block.talos.dev resource. talosctl disks is a separate command with different output.
• --stage/--preserve flags deprecated — Legacy flags in v1.13+, removed in Talos 1.18. Use --no-reboot instead of --stage.
• Apply config to all nodes at once — For CP changes, use sequential apply with health checks between nodes (etcd quorum).
• talosctl reset without --graceful=false — By default --graceful=true which cordons/drains and removes from etcd. Set --graceful=false --reboot for hard reset.
• talosctl get machineconfig without ID — Needs the resource ID: talosctl get machineconfig v1alpha1.
• Wrong diagnostics commands — interfaces/routes are NOT talosctl commands. Use talosctl get links / talosctl get routes.