Skip to main content

​
Overview

Cluster commands manage local Talos Linux clusters for development and testing. These clusters can be created using Docker or QEMU as the provisioner.

​
cluster create

Create a local Talos Kubernetes cluster for development and testing. 
talosctl cluster create [flags]

​
Description

Creates a local Talos cluster using Docker containers or QEMU VMs. The cluster includes control plane and worker nodes with networking configured automatically.

​
Flags

​
--name
string
default:"talos-default"
Name of the clusterExample:
talosctl cluster create --name my-dev-cluster
​
--provisioner
string
default:"docker"
Talos cluster provisioner to use (docker or qemu)Example:
talosctl cluster create --provisioner qemu
​
--state
string
Directory path to store cluster stateDefault: ~/.talos/clusters
​
--controlplanes
int
default:"1"
Number of control plane nodesExample:
talosctl cluster create --controlplanes 3
​
--workers
int
default:"0"
Number of worker nodesExample:
talosctl cluster create --workers 2
​
--cpus
string
default:"2.0"
Number of CPUs per nodeExample:
talosctl cluster create --cpus 4.0
​
--memory
int
default:"2048"
Memory (MB) per nodeExample:
talosctl cluster create --memory 4096
​
--disk
int
default:"6144"
Disk size (MB) per nodeExample:
talosctl cluster create --disk 10240
​
--install-image
string
The installer image to useDefault: Latest Talos installer imageExample:
talosctl cluster create --install-image ghcr.io/siderolabs/installer:v1.8.0
​
--with-init-node
boolean
default:"true"
Create the cluster with an init node
​
--kubernetes-version
string
Desired Kubernetes version to runExample:
talosctl cluster create --kubernetes-version 1.31.0
​
--endpoint
string
Use a custom endpoint for the cluster endpoint
​
--skip-injecting-config
boolean
default:"false"
Skip injecting the Talos API config into the generated talosconfig
​
--talos-version
string
The desired Talos version to use for the cluster
​
--encrypt-ephemeral
boolean
default:"false"
Enable ephemeral partition encryption
​
--encrypt-state
boolean
default:"false"
Enable state partition encryption

​
Examples

Create a simple single-node cluster 
talosctl cluster create
Create a 3 control plane + 2 worker cluster 
talosctl cluster create \
  --name production-like \
  --controlplanes 3 \
  --workers 2 \
  --cpus 4.0 \
  --memory 8192
Create a cluster with specific Kubernetes version 
talosctl cluster create \
  --name k8s-1-30 \
  --kubernetes-version 1.30.0
Create a cluster with QEMU provisioner 
talosctl cluster create \
  --provisioner qemu \
  --name qemu-cluster \
  --controlplanes 1 \
  --workers 1
Output: 
validating CIDR and reserving IPs
generated talosconfig for cluster talos-default
provisioning nodes
creating load balancer
creating control plane node talos-default-controlplane-1
creating worker node talos-default-worker-1
waiting for API
bootstrapping cluster
waiting for etcd
waiting for kubelet
waiting for services
Kubernetes cluster ready!

​
cluster destroy

Destroy a local Talos Kubernetes cluster. 
talosctl cluster destroy [flags]

​
Description

Destroys a previously created local cluster, removing all containers/VMs and associated resources.

​
Flags

​
--name
string
default:"talos-default"
Name of the cluster to destroy
​
--state
string
Directory path where cluster state is storedDefault: ~/.talos/clusters
​
--force
boolean
default:"false"
Force deletion of cluster directory if there were errorsShort flag: -fExample:
talosctl cluster destroy --force
​
--save-support-archive-path
string
Save support archive to the specified file on destroyExample:
talosctl cluster destroy --save-support-archive-path ./support.zip
​
--save-cluster-logs-archive-path
string
Save cluster logs archive to the specified file on destroyExample:
talosctl cluster destroy --save-cluster-logs-archive-path ./logs.tar.gz

​
Examples

Destroy the default cluster 
talosctl cluster destroy
Destroy a specific cluster 
talosctl cluster destroy --name my-dev-cluster
Destroy and save diagnostics 
talosctl cluster destroy \
  --name my-cluster \
  --save-support-archive-path ./diagnostics.zip \
  --save-cluster-logs-archive-path ./logs.tar.gz
Force destroy even if errors occur 
talosctl cluster destroy --force
Output: 
destroying node talos-default-controlplane-1
destroying node talos-default-worker-1
destroying load balancer
removing cluster state directory

​
cluster show

Show details about a local Talos cluster. 
talosctl cluster show [flags]

​
Description

Displays information about a running local cluster including node IPs, roles, and status.

​
Flags

​
--name
string
default:"talos-default"
Name of the cluster to show
​
--state
string
Directory path where cluster state is storedDefault: ~/.talos/clusters

​
Examples

Show default cluster 
talosctl cluster show
Show specific cluster 
talosctl cluster show --name production-like
Output: 
NAME                              ROLE              IPS               STATE
talos-default-controlplane-1      controlplane      172.20.0.2        running
talos-default-worker-1            worker            172.20.0.3        running

Provisioner: docker
Kubernetes API: https://172.20.0.2:6443
Talos API: 172.20.0.2

​
Common Workflows

​
Development Cluster Lifecycle

Create a development cluster 
talosctl cluster create --name dev --workers 1
Get cluster information 
talosctl cluster show --name dev
Use the cluster 
export KUBECONFIG=~/.talos/clusters/dev/kubeconfig
kubectl get nodes
Clean up 
talosctl cluster destroy --name dev

​
Testing Different Configurations

Test with encryption enabled 
talosctl cluster create \
  --name encrypted-test \
  --encrypt-state \
  --encrypt-ephemeral
Test with specific Talos version 
talosctl cluster create \
  --name version-test \
  --talos-version v1.7.0 \
  --kubernetes-version 1.30.0

​
Multi-Node Testing

Create a realistic cluster 
talosctl cluster create \
  --name ha-test \
  --controlplanes 3 \
  --workers 3 \
  --cpus 2.0 \
  --memory 4096
Verify cluster health 
talosctl --context ha-test health \
  --control-plane-nodes 172.20.0.2,172.20.0.3,172.20.0.4 \
  --worker-nodes 172.20.0.5,172.20.0.6,172.20.0.7

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us