Talos cluster

A comprehensive, step-by-step guide to deploying multi-node Talos Linux Kubernetes cluster from scratch.

What is Talos Linux?

Talos Linux is a modern, secure, and minimal Linux distribution designed specifically for Kubernetes. Unlike traditional Linux distributions, Talos is:

Immutable: The OS cannot be modified at runtime, ensuring consistency
API-managed: All configuration is done via a declarative API
Minimal: Only includes what’s necessary to run Kubernetes
Secure by default: No SSH, no shell, reduced attack surface

Learn more in the official Talos documentation.

Prerequisites

1. Control Machine Setup

You need a Linux machine (physical, VM, or WSL2) to orchestrate the deployment. This machine will NOT be part of the cluster; it’s just your workstation.

Install talosctl (Talos CLI):
Install kubectl (Kubernetes CLI)

2. Prepare Cluster Nodes

You need physical or virtual machines with Talos Linux installed. For this guide, we’ll assume:

1 control plane node: Will run the Kubernetes control plane and etcd
2 worker nodes: Will run your application workloads

Minimum requirements per node:

2+ CPU cores (4 recommended)
4GB RAM (8GB recommended for control plane)
50GB+ disk space
Network connectivity between all nodes

Getting Your Talos Factory Image

Talos uses a “factory” system to generate custom installation images with system extensions (drivers, plugins, etc.). You need to determine which image matches your hardware.

Step 1: Visit the Talos Image Factory

Go to https://factory.talos.dev/

Step 2: Select System Extensions (if needed)

Common extensions include:

qemu-guest-agent: For Proxmox/QEMU VMs
iscsi-tools: For iSCSI storage
siderolabs/util-linux-tools

For a basic setup without special hardware, you can use the default image with no extensions. The two last tools are used for setting up CSI, we highly recommend installing them.

Step 3: Copy Your Image Identifier

The factory will generate an installer URL that looks like:

https://factory.talos.dev/image/88d1f7a5c4f1d3aba7df787c448c1d3d008ed29cfb34af53fa0df4336a56040b/v1.12.0/metal-amd64.iso

This identifier is unique to your selected extensions. Save this—you’ll need it in the next section.

Step 4: Bootup the VMs with the talos image

proceed to bootup the 3 vms with this image, after bootup, each vm will show a talos control plan which contains the state of the talos machine as well as their IPS.

Environment Configuration

Now let’s set up your environment variables. These will be used throughout the deployment process. for a highly available cluster you should have 3 control plane nodes Open a terminal and export these variables (adjust IPs to match your infrastructure):

# Cluster identification
export CLUSTER_NAME="my-talos-cluster"
export CONTROL_PLANE_IP="192.168.1.101"  # First control plane node

# Where to store generated configurations
export CONFIG_PATH="$HOME/.config/talos-cluster"

# Your control plane node IPs (space-separated)
export CONTROL_PLANE_NODES="192.168.1.101"

# Your worker node IPs (space-separated)
export WORKER_NODES="192.168.1.104 192.168.1.105"

# Talos factory image (from previous section)
export INSTALL_IMAGE=
"https://factory.talos.dev/image/88d1f7a5c4f1d3aba7df787c448c1d3d008ed29cfb34af53fa0df4336a56040b/v1.12.0/metal-amd64.iso"

Important: These variables only persist in your current shell session. If you close your terminal, you’ll need to export them again, or add them to a script/file that you can source. Pro tip: Save these to a file for easy reuse:

cat > ~/talos-cluster-env.sh << 'EOF'
export CLUSTER_NAME="my-talos-cluster"
export CONTROL_PLANE_IP="192.168.1.101"
export CONFIG_PATH="$HOME/.config/talos-cluster"
export CONTROL_PLANE_NODES="192.168.1.101"
export WORKER_NODES="192.168.1.104 192.168.1.105"
export INSTALL_IMAGE="https://factory.talos.dev/image/88d1f7a5c4f1d3aba7df787c448c1d3d008ed29cfb34af53fa0df4336a56040b/v1.12.0/metal-amd64.iso"
EOF

# Load them anytime with:
source ~/talos-cluster-env.sh

Step-by-Step Deployment

Step 1: Generate Cluster Configuration Files

Talos needs configuration files that define how each node should behave. We’ll generate these now.

# Create output directory
mkdir -p "$CONFIG_PATH"

# Generate configurations
talosctl gen config \
  "$CLUSTER_NAME" \
  "https://$CONTROL_PLANE_IP:6443" \
  --output-dir "$CONFIG_PATH" \
  --install-image "$INSTALL_IMAGE"

What’s happening here:

talosctl gen config creates three files:
- controlplane.yaml: Configuration for control plane nodes
- worker.yaml: Configuration for worker nodes
- talosconfig: Authentication credentials for managing the cluster
The --install-image flag tells Talos which image to use (with your hardware-specific extensions)
The cluster endpoint URL (https://$CONTROL_PLANE_IP:6443) is where kubectl will connect

Expected output:

generating PKI and tokens
Created /home/user/.config/talos-cluster/controlplane.yaml
Created /home/user/.config/talos-cluster/worker.yaml
Created /home/user/.config/talos-cluster/talosconfig

What just happened:

Talos generated cryptographic certificates for secure communication
Created machine configurations with your cluster name and endpoint
Generated credentials for you to manage the cluster

Merge talosconfig into your local configuration:

talosctl config merge "$CONFIG_PATH/talosconfig"

This allows talosctl commands to authenticate with your cluster.

Step 2: Apply Configuration to Control Plane Nodes

Now we’ll push the control plane configuration to each control plane node. This tells them they’re control plane nodes and gives them their identity.

# Apply to each control plane node
for IP in $CONTROL_PLANE_NODES; do
  echo "→ Configuring control plane node: $IP"
  talosctl apply-config \
    --insecure \
    --nodes "$IP" \
    --file "$CONFIG_PATH/controlplane.yaml"
  echo "✓ Configuration applied to $IP"
done

What’s happening here:

--insecure flag: Required on first boot because nodes don’t have certificates yet
--nodes: Specifies which node to configure
--file: The configuration file to apply
After applying, each node will reboot to apply the configuration

What you’ll see:

→ Configuring control plane node: 192.168.1.101
✓ Configuration applied to 192.168.1.101

Wait 2-5 minutes for all control plane nodes to complete their reboot cycle.

Step 3: Apply Configuration to Worker Nodes

Same process, but for worker nodes. These nodes will run your application workloads. Execute:

# Apply to each worker node
for IP in $WORKER_NODES; do
  echo "→ Configuring worker node: $IP"
  talosctl apply-config \
    --insecure \
    --nodes "$IP" \
    --file "$CONFIG_PATH/worker.yaml"
  echo "✓ Configuration applied to $IP"
done

Wait another 2-5 minutes for worker nodes to reboot and apply configuration. Verify nodes are responsive:

# Check control plane nodes
for IP in $CONTROL_PLANE_NODES; do
  echo "Checking $IP..."
  talosctl --nodes "$IP" version
done

# Check worker nodes
for IP in $WORKER_NODES; do
  echo "Checking $IP..."
  talosctl --nodes "$IP" version
done

You should see version information for each node. If you get connection errors, wait a bit longer; nodes might still be rebooting.

Step 4: Bootstrap the Cluster

This is the critical step where we initialize etcd and start Kubernetes. This must only be done once per cluster. Select one control plane node (in our case we only have one)

# Set the endpoint and node for talosctl
talosctl config endpoint "$CONTROL_PLANE_IP"
talosctl config node "$CONTROL_PLANE_IP"

# Bootstrap the cluster
echo "Bootstrapping etcd and Kubernetes control plane..."
talosctl bootstrap

What’s happening here:

We’re telling talosctl which node to communicate with (the first control plane node)
The bootstrap command initializes etcd on this node
etcd is the distributed database that stores all Kubernetes state
Other control plane nodes will automatically join the etcd cluster
Kubernetes control plane components will start

⚠️ CRITICAL WARNING:

Wait One More Thing Charlie GIFfrom Wait One More Thing GIFs

DO NOT run talosctl bootstrap more than once. Running it again will destroy your etcd cluster and you’ll lose all data. If you accidentally run it twice, you’ll need to wipe all nodes and start over. What’s happening in the background:

First control plane node starts etcd
etcd creates the initial cluster state
Kubernetes API server starts
Controller manager and scheduler start
Other control plane nodes detect the running cluster and join
Worker nodes connect to the API server and join as compute nodes

Wait 2-3 minutes for Kubernetes to fully initialize. Verify the bootstrap:

# Check etcd health
talosctl etcd members

# Check services
talosctl services

You should see etcd, kubelet, and other services running.

Step 5: Retrieve Kubeconfig

Now we need the kubeconfig file so kubectl can communicate with your cluster.

# Retrieve kubeconfig
talosctl kubeconfig "$CONFIG_PATH"

What’s happening here:

Talos generates a kubeconfig file with admin credentials
This file contains the cluster endpoint and authentication certificates
kubectl will use this to communicate with the Kubernetes API

Expected output:

downloading kubeconfig from node 192.168.1.101
kubeconfig written to /home/user/.config/talos-cluster/kubeconfig

Set KUBECONFIG environment variable:

export KUBECONFIG="$CONFIG_PATH/kubeconfig"

Verify kubectl connectivity:

kubectl cluster-info

Expected output:

Kubernetes control plane is running at https://192.168.1.101:6443
CoreDNS is running at https://192.168.1.101:6443/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy

Understanding What We Built

Architecture Overview

Your cluster now has: Control Plane Node (1):

Running etcd (distributed database)
Running Kubernetes API server
Running scheduler (assigns pods to nodes)
Running controller manager (maintains desired state)

Worker Nodes (2):

Running kubelet (node agent)
Running container runtime
Ready to run your application pods

Networking:

Flannel CNI for pod networking

Completely Reset a Node

If a node is broken beyond repair:

talosctl reset --nodes <NODE_IP> --graceful=false --reboot

Then reapply configuration from Step 2 or 3.

Upgrading Talos

When a new Talos version is released:

# Upgrade control plane nodes one at a time
talosctl upgrade --nodes 192.168.1.101 \
  --image factory.talos.dev/installer/<YOUR_EXTENSIONS>:v1.12.0

# Wait for node to come back up, then next node
talosctl upgrade --nodes 192.168.1.102 \
  --image factory.talos.dev/installer/<YOUR_EXTENSIONS>:v1.12.0

# Continue for remaining nodes...

Smiling Friends Mr Boss GIFfrom Smiling Friends GIFs

Congratulations! You now have a multi-node Kubernetes cluster running on Talos Linux! 🎉

Getting Started

Deployment

Kubernetes

AI

What is Talos Linux?

Prerequisites

1. Control Machine Setup

2. Prepare Cluster Nodes

Getting Your Talos Factory Image

Step 1: Visit the Talos Image Factory

Step 2: Select System Extensions (if needed)

Step 3: Copy Your Image Identifier

Step 4: Bootup the VMs with the talos image

Environment Configuration

Step-by-Step Deployment

Step 1: Generate Cluster Configuration Files

Step 2: Apply Configuration to Control Plane Nodes

Step 3: Apply Configuration to Worker Nodes

Step 4: Bootstrap the Cluster

Step 5: Retrieve Kubeconfig

Understanding What We Built

Architecture Overview

Completely Reset a Node

Upgrading Talos

​What is Talos Linux?

​Prerequisites

​1. Control Machine Setup

​2. Prepare Cluster Nodes

​Getting Your Talos Factory Image

​Step 1: Visit the Talos Image Factory

​Step 2: Select System Extensions (if needed)

​Step 3: Copy Your Image Identifier

​Step 4: Bootup the VMs with the talos image

​Environment Configuration

​Step-by-Step Deployment

​Step 1: Generate Cluster Configuration Files

​Step 2: Apply Configuration to Control Plane Nodes

​Step 3: Apply Configuration to Worker Nodes

​Step 4: Bootstrap the Cluster

​Step 5: Retrieve Kubeconfig

​Understanding What We Built

​Architecture Overview

​Completely Reset a Node

​Upgrading Talos

What is Talos Linux?

Prerequisites

1. Control Machine Setup

2. Prepare Cluster Nodes

Getting Your Talos Factory Image

Step 1: Visit the Talos Image Factory

Step 2: Select System Extensions (if needed)

Step 3: Copy Your Image Identifier

Step 4: Bootup the VMs with the talos image

Environment Configuration

Step-by-Step Deployment

Step 1: Generate Cluster Configuration Files

Step 2: Apply Configuration to Control Plane Nodes

Step 3: Apply Configuration to Worker Nodes

Step 4: Bootstrap the Cluster

Step 5: Retrieve Kubeconfig

Understanding What We Built

Architecture Overview

Completely Reset a Node

Upgrading Talos