Node Commands

Overview

Node commands perform operations on running Talos nodes, including lifecycle management, upgrades, and maintenance tasks.

reboot

Reboot a Talos node.

talosctl reboot [flags]

Description

Reboots one or more Talos nodes. The command can wait for the reboot to complete and verify the node comes back online.

Flags

--mode

string

default:"default"

Select the reboot modeOptions:

default - Standard reboot with kexec
powercycle - Skip kexec and reboot with power cycle
force - Skip graceful teardown (emergency use only)

Short flag: -mExample:

talosctl reboot --mode powercycle

--wait

boolean

default:"false"

Wait for the reboot to complete and node to be readyExample:

talosctl reboot --wait

--timeout

duration

default:"30m"

Timeout to wait for the operationOnly applicable when --wait is used.Example:

talosctl reboot --wait --timeout 10m

--debug

boolean

default:"false"

Enable debug mode (implies —wait)Example:

talosctl reboot --debug

Examples

Reboot a single node

talosctl -n 10.5.0.2 reboot

Reboot and wait for completion

talosctl -n 10.5.0.2 reboot --wait

Force reboot with power cycle

talosctl -n 10.5.0.2 reboot --mode powercycle

Reboot with debug output

talosctl -n 10.5.0.2 reboot --debug

Output:

node 10.5.0.2: rebooting
waiting for node to reboot...
node 10.5.0.2: reboot successful

shutdown

Shutdown a Talos node.

talosctl shutdown [flags]

Description

Shuts down one or more Talos nodes gracefully, cordoning and draining Kubernetes workloads if applicable.

Flags

--force

boolean

default:"false"

Force a node to shutdown without cordon/drainExample:

talosctl shutdown --force

--wait

boolean

default:"false"

Wait for the shutdown to completeExample:

talosctl shutdown --wait

--timeout

duration

default:"30m"

Timeout to wait for the operationExample:

talosctl shutdown --wait --timeout 10m

--debug

boolean

default:"false"

Enable debug mode (implies —wait)

Examples

Shutdown a node gracefully

talosctl -n 10.5.0.3 shutdown

Force shutdown without draining

talosctl -n 10.5.0.3 shutdown --force

Shutdown and wait

talosctl -n 10.5.0.3 shutdown --wait

Output:

node 10.5.0.3: shutting down

upgrade

Upgrade Talos on the target node.

talosctl upgrade [flags]

Description

Upgrades the Talos installation on one or more nodes to a specified version. The upgrade can be staged to apply after a manual reboot.

Flags

--image

string

The container image to use for performing the upgradeDefault: Latest Talos installer imageShort flag: -iExample:

talosctl upgrade --image ghcr.io/siderolabs/installer:v1.8.0

--reboot-mode

string

default:"default"

Select the reboot mode during upgradeOptions:

default - Standard reboot
powercycle - Bypass kexec

Short flag: -mExample:

talosctl upgrade -i ghcr.io/siderolabs/installer:v1.8.0 --reboot-mode powercycle

--stage

boolean

default:"false"

Stage the upgrade to perform it after a rebootShort flag: -sExample:

talosctl upgrade --image ghcr.io/siderolabs/installer:v1.8.0 --stage

--force

boolean

default:"false"

Force the upgrade (skip checks on etcd health and members)Warning: Might lead to data lossShort flag: -fExample:

talosctl upgrade -i ghcr.io/siderolabs/installer:v1.8.0 --force

--wait

boolean

default:"false"

Wait for the upgrade to completeExample:

talosctl upgrade -i ghcr.io/siderolabs/installer:v1.8.0 --wait

--timeout

duration

default:"30m"

Timeout to wait for the operation

--debug

boolean

default:"false"

Enable debug mode (implies —wait)

--insecure

boolean

default:"false"

Upgrade using the insecure (encrypted with no auth) maintenance service

Examples

Upgrade to specific version

talosctl -n 10.5.0.2 upgrade --image ghcr.io/siderolabs/installer:v1.8.0

Stage an upgrade

talosctl -n 10.5.0.2 upgrade \
  --image ghcr.io/siderolabs/installer:v1.8.0 \
  --stage

Upgrade and wait for completion

talosctl -n 10.5.0.2 upgrade \
  --image ghcr.io/siderolabs/installer:v1.8.0 \
  --wait

Force upgrade on a degraded node

talosctl -n 10.5.0.2 upgrade \
  --image ghcr.io/siderolabs/installer:v1.8.0 \
  --force

Output:

NODE         ACK     STARTED
10.5.0.2     v1.8.0  2024-01-15T10:30:00Z

reset

Reset a Talos node to factory defaults.

talosctl reset [flags]

Description

Resets a node by wiping system disk(s) and optionally rebooting. This operation removes all data and returns the node to a clean state.

Flags

--graceful

boolean

default:"true"

Attempt to cordon/drain node and leave etcd (if applicable)Example:

talosctl reset --graceful=false

--reboot

boolean

default:"false"

Reboot the node after resetting instead of shutting downExample:

talosctl reset --reboot

--wipe-mode

string

default:"all"

Disk reset modeOptions:

all - Wipe system disk and user disks
system-disk - Wipe only system disk
user-disks - Wipe only user disks

Example:

talosctl reset --wipe-mode system-disk

--user-disks-to-wipe

string[]

List of user disk devices to wipeExample:

talosctl reset --user-disks-to-wipe /dev/sdb,/dev/sdc

--system-labels-to-wipe

string[]

System disk partitions to wipe by labelWipes only selected partitions but keeps others intact.Example:

talosctl reset --system-labels-to-wipe STATE,EPHEMERAL

--insecure

boolean

default:"false"

Reset using the insecure (encrypted with no auth) maintenance serviceExample:

talosctl reset --insecure

--wait

boolean

default:"false"

Wait for the reset to complete

--timeout

duration

default:"30m"

Timeout to wait for the operation

--debug

boolean

default:"false"

Enable debug mode (implies —wait)

Examples

Reset a node (default behavior)

talosctl -n 10.5.0.4 reset

Reset and reboot

talosctl -n 10.5.0.4 reset --reboot

Reset only system disk

talosctl -n 10.5.0.4 reset --wipe-mode system-disk

Reset specific user disks

talosctl -n 10.5.0.4 reset --user-disks-to-wipe /dev/sdb,/dev/sdc

Reset with insecure mode

talosctl -n 10.5.0.4 reset --insecure --reboot

Wipe only specific partitions

talosctl -n 10.5.0.4 reset --system-labels-to-wipe EPHEMERAL

Output:

node 10.5.0.4: resetting

bootstrap

Bootstrap the etcd cluster on the specified node.

talosctl bootstrap [flags]

Description

When a Talos cluster is created, etcd services on control plane nodes enter a join loop waiting for other members. One node should be selected as the bootstrap node to initialize the etcd cluster. Important: This command should not be used when “init” type nodes are configured.

Flags

--recover-from

string

Recover etcd cluster from a snapshot fileExample:

talosctl bootstrap --recover-from ./etcd-snapshot.db

--recover-skip-hash-check

boolean

default:"false"

Skip integrity check when recovering etcdUse when recovering from a data directory copy.Example:

talosctl bootstrap --recover-from ./etcd-snapshot.db --recover-skip-hash-check

Examples

Bootstrap etcd on the first control plane node

talosctl -n 10.5.0.2 bootstrap

Recover from an etcd snapshot

talosctl -n 10.5.0.2 bootstrap --recover-from ./etcd-backup.db

Output:

recovering from snapshot "./etcd-backup.db": hash 5a3c2f1e, revision 12345, total keys 100, total size 1048576
bootstrapping etcd cluster

version

Print version information for client and server.

talosctl version [flags]

Description

Displays version information for both the talosctl client and the Talos nodes.

Flags

--client

boolean

default:"false"

Print client version onlyExample:

talosctl version --client

--short

boolean

default:"false"

Print the short versionExample:

talosctl version --short

--insecure

boolean

default:"false"

Use Talos maintenance mode APIShort flag: -iExample:

talosctl version --insecure

Examples

Show all version information

talosctl version

Show only client version

talosctl version --client

Show short version

talosctl version --short

Output:

Client:
	Tag:         v1.8.0
	SHA:         abc123def456
	Built:       2024-01-15T10:30:00Z
	Go version:  go1.21.5
	OS/Arch:     linux/amd64
Server:
	NODE:        10.5.0.2
	Tag:         v1.8.0
	SHA:         abc123def456
	Built:       2024-01-15T10:30:00Z
	Go version:  go1.21.5
	OS/Arch:     linux/amd64
	Enabled:     RBAC

Common Workflows

Rolling Node Upgrades

# Upgrade control plane nodes one at a time
talosctl -n 10.5.0.2 upgrade --image ghcr.io/siderolabs/installer:v1.8.0 --wait
talosctl -n 10.5.0.3 upgrade --image ghcr.io/siderolabs/installer:v1.8.0 --wait
talosctl -n 10.5.0.4 upgrade --image ghcr.io/siderolabs/installer:v1.8.0 --wait

# Upgrade worker nodes
talosctl -n 10.5.0.5,10.5.0.6 upgrade --image ghcr.io/siderolabs/installer:v1.8.0

Maintenance Mode Recovery

# Reset a node to maintenance mode
talosctl -n 10.5.0.5 reset --insecure

# Apply new configuration in maintenance mode
talosctl -n 10.5.0.5 apply-config --insecure -f worker.yaml

Staged Upgrades

# Stage upgrade on all nodes
talosctl -n 10.5.0.2,10.5.0.3,10.5.0.4 upgrade \
  --image ghcr.io/siderolabs/installer:v1.8.0 \
  --stage

# Reboot nodes during maintenance window
talosctl -n 10.5.0.2 reboot --wait
talosctl -n 10.5.0.3 reboot --wait
talosctl -n 10.5.0.4 reboot --wait

CLI Reference

gRPC API

Configuration API

Overview

reboot

Description

Flags

Examples

shutdown

Description

Flags

Examples

upgrade

Description

Flags

Examples

reset

Description

Flags

Examples

bootstrap

Description

Flags

Examples

version

Description

Flags

Examples

Common Workflows

Rolling Node Upgrades

Maintenance Mode Recovery

Staged Upgrades

See Also

Build docs developers (and LLMs) love

CLI Reference

gRPC API

Configuration API

​Overview

​reboot

​Description

​Flags

​Examples

​shutdown

​Description

​Flags

​Examples

​upgrade

​Description

​Flags

​Examples

​reset

​Description

​Flags

​Examples

​bootstrap

​Description

​Flags

​Examples

​version

​Description

​Flags

​Examples

​Common Workflows

​Rolling Node Upgrades

​Maintenance Mode Recovery

​Staged Upgrades

​See Also

Build docs developers (and LLMs) love

Overview

reboot

Description

Flags

Examples

shutdown

Description

Flags

Examples

upgrade

Description

Flags

Examples

reset

Description

Flags

Examples

bootstrap

Description

Flags

Examples

version

Description

Flags

Examples

Common Workflows

Rolling Node Upgrades

Maintenance Mode Recovery

Staged Upgrades

See Also