Install Talos Linux on Proxmox: Kubernetes Cluster Step by Step

Building a production Talos cluster on Proxmox? WZ-IT designs Proxmox hosts, failure domains, networking and storage together with the Kubernetes layer and can operate the platform afterwards. Kubernetes on Proxmox as a service

Talos Linux is an immutable operating system that runs nothing but Kubernetes and is managed exclusively through an API. On Proxmox it runs in KVM VMs that boot from an Image Factory ISO. This guide goes from the image to a highly available cluster with three control planes, a virtual IP for the Kubernetes API, CNI, Proxmox storage integration and an upgrade path. The commands follow the official Talos Proxmox guide and the production notes, extended with the Proxmox-side settings.

Whether Talos is the right distribution in the first place is covered in k3s vs. RKE2 vs. Talos. The architecture questions around Proxmox and Kubernetes, such as VM or LXC, storage and backup, are covered in Kubernetes on Proxmox.

Table of contents

• Status and prerequisites
• Step 1: Talos image from the Image Factory
• Step 2: Create control-plane and worker VMs in Proxmox
• Step 3: Check the network interface and disk
• Step 4: Generate the machine configuration with a virtual IP
• Step 5: Apply the configuration
• Step 6: Bootstrap the cluster and retrieve the kubeconfig
• CNI: Flannel or Cilium
• Proxmox CSI and cloud controller manager
• Upgrades: Talos and Kubernetes separately
• Common mistakes
• Outlook: Terraform and OpenTofu
• How WZ-IT works
• Further guides

Status and prerequisites

As of 18 October 2026, Talos Linux v1.14.4, released on 16 October 2026, is the current stable release. It ships Kubernetes 1.37.1 and Linux 6.18.57; according to the support matrix, Talos 1.14 supports Kubernetes 1.33 to 1.37. Since Talos 1.14, the installer image is no longer published as ghcr.io/siderolabs/installer but served exclusively by the Image Factory as factory.talos.dev/metal-installer/<schematic-id>:<version>.

A highly available cluster requires:

• Three Proxmox hosts in one cluster, so that each control-plane VM runs on its own physical host. A single host is enough for a lab. The base installation is covered in Install Proxmox, the cluster in Building an HA cluster with Proxmox.
• A shared Layer 2 network for the control-plane nodes. The Talos virtual IP requires all control planes to sit in the same subnet with no router in between.
• Fixed addresses: one IP per node, most simply as a DHCP reservation, and one free IP outside the DHCP range for the virtual IP of the Kubernetes API.
• talosctl and kubectl on the admin machine. Installing talosctl on macOS and Linux works through Homebrew or an install script. The talosctl version should match the Talos version on the nodes.

brew install siderolabs/tap/talosctl
# alternatively without Homebrew: download, read, then run the script
curl -fsSLo talos-install.sh https://talos.dev/install
less talos-install.sh
sh talos-install.sh

This guide targets the following cluster. The values combine the recommendations of the Proxmox guide with the system requirements:

Schematic target design:

Kubernetes API: VIP 192.168.10.50
              |          |          |
Proxmox Host 1     Host 2     Host 3
        CP .11     CP .12     CP .13
        Worker .21           Worker .22

Proxmox hardware and sizing explains host capacity planning.

The examples use the network 192.168.10.0/24 with control planes .11 to .13, workers .21 and .22 and the virtual IP .50.

Step 1: Talos image from the Image Factory

The Image Factory builds Talos images from a schematic that defines system extensions and kernel arguments. Schematics are content-addressable: the same content always produces the same ID. The default schematic without customizations has the ID 376567988ad370138ad8b2698212367b8edcb69b5fd68c80be1f2ec7d603b4ba.

For Proxmox, the siderolabs/qemu-guest-agent extension is recommended. According to the Talos guide it is optional and needed for VM shutdowns through the QEMU guest agent. The schematic can be assembled in the web UI at factory.talos.dev or created through the API:

cat > schematic.yaml <<'EOF'
customization:
  systemExtensions:
    officialExtensions:
      - siderolabs/qemu-guest-agent
EOF

curl -X POST --data-binary @schematic.yaml https://factory.talos.dev/schematics
# {"id":"ce4c980550dd2ab1b17bbf2b08801c7eb59418eafe8f279833297925d67c7515", ...}

With this ID, the ISO is downloaded directly on a Proxmox host into the ISO storage of the local storage (directory /var/lib/vz/template/iso). Alternatively, upload it in the Proxmox web UI under local > ISO Images > Upload.

export TALOS_VERSION=v1.14.4
export SCHEMATIC_ID=ce4c980550dd2ab1b17bbf2b08801c7eb59418eafe8f279833297925d67c7515

cd /var/lib/vz/template/iso
wget -O talos-${TALOS_VERSION}-qemu-ga-amd64.iso \
  https://factory.talos.dev/image/${SCHEMATIC_ID}/${TALOS_VERSION}/metal-amd64.iso

The same schematic maps to the installer image factory.talos.dev/metal-installer/ce4c980550dd2ab1b17bbf2b08801c7eb59418eafe8f279833297925d67c7515:v1.14.4. Step 4 writes it into the machine configuration so the extension is kept after installation to disk, and it is used again for upgrades.

Step 2: Create control-plane and worker VMs in Proxmox

The Talos Proxmox guide recommends the following settings for all Talos nodes:

Instead of clicking through the eight tabs of the wizard, qm creates the VM with the same values on the respective Proxmox host. The example creates the first control plane; adjust storage names, VM IDs and sizes to your environment. The options are documented in the qm manual.

qm create 111 --name talos-cp-1 --ostype l26 \
  --bios ovmf --machine q35 \
  --efidisk0 local-lvm:1,efitype=4m,pre-enrolled-keys=0 \
  --cpu host --cores 4 --memory 4096 --balloon 0 \
  --scsihw virtio-scsi-pci \
  --scsi0 local-lvm:100,cache=writethrough,discard=on,ssd=1 \
  --net0 virtio,bridge=vmbr0 \
  --ide2 local:iso/talos-v1.14.4-qemu-ga-amd64.iso,media=cdrom \
  --boot 'order=scsi0;ide2' \
  --agent enabled=1 \
  --serial0 socket

--scsihw virtio-scsi-pci corresponds to "VirtIO SCSI" in the web UI, and --balloon 0 disables the balloon driver, which according to the Proxmox documentation is otherwise added even with a fixed memory size. The Talos guide recommends the serial console to see early boot logs and network problems. Create the control planes talos-cp-2 and talos-cp-3 on the other two Proxmox hosts, and the workers with at least 4 cores and 8 GB RAM.

Two consequences of these settings belong in the plan:

• CPU type host and live migration: The Talos guide notes that the host CPU type prevents live migration. Proxmox describes the general issue: on a target host with a different CPU or microcode, flags are missing and the QEMU process stops. With Talos this is acceptable, because nodes are drained and rebooted with talosctl for maintenance instead of being moved between hosts.
• Keep control planes apart: If Proxmox HA manages the Talos VMs, a resource affinity rule with negative affinity prevents HA from starting two control planes on the same host after a failure.

ha-manager rules add resource-affinity talos-cp-apart \
  --affinity negative --resources vm:111,vm:112,vm:113

Step 3: Check the network interface and disk

After start-up, the VMs boot from the ISO into maintenance mode. The system then runs entirely in memory, and the Proxmox console shows the IP address obtained via DHCP. Without DHCP, the guide adds the address as the ip= kernel argument after pressing e in the GRUB menu.

In maintenance mode, the Talos API is unauthenticated by design: anyone who can reach the network can apply a configuration. The installation network therefore must not be exposed to the internet.

CONTROL_PLANE_IP=("192.168.10.11" "192.168.10.12" "192.168.10.13")
WORKER_IP=("192.168.10.21" "192.168.10.22")

talosctl --nodes 192.168.10.11 get links --insecure
talosctl get disks --insecure --nodes 192.168.10.11

From get links, take the name of the interface whose operational state is up. Since version 1.5, Talos uses predictable interface names, so the NIC is not necessarily called eth0. get disks shows the install disk. The default target is /dev/sda, which usually matches a disk on the VirtIO SCSI controller. If the path differs, set it with --install-disk when generating the configuration.

Step 4: Generate the machine configuration with a virtual IP

Talos ships a virtual IP for the Kubernetes API: the control-plane nodes assign the address among themselves through an etcd election, so no external load balancer is needed. If the holder shuts down gracefully, the address moves almost instantly; after a crash, failover takes up to about a minute. In Talos 1.14, the VIP is configured as a separate Layer2VIPConfig document:

cat > vip.yaml <<'EOF'
apiVersion: v1alpha1
kind: Layer2VIPConfig
name: 192.168.10.50
link: <interface-from-get-links>
EOF

Next, create the secrets bundle and the machine configuration. The secrets bundle contains all keys, certificates and tokens of the cluster and must be protected like a password vault. The Kubernetes endpoint points to the VIP, and the installer image comes from step 1:

export CLUSTER_NAME=talos-proxmox
export VIP=192.168.10.50

talosctl gen secrets -o secrets.yaml

talosctl gen config --with-secrets secrets.yaml \
  --install-image factory.talos.dev/metal-installer/${SCHEMATIC_ID}:${TALOS_VERSION} \
  --config-patch-control-plane @vip.yaml \
  --output _out \
  $CLUSTER_NAME https://$VIP:6443

The _out directory then contains controlplane.yaml, worker.yaml and talosconfig. Further adjustments such as static addresses, labels or a different CNI are added the same way as configuration patches instead of editing the generated files by hand.

Step 5: Apply the configuration

The configuration is applied in maintenance mode with --insecure. Talos then installs itself to disk and reboots.

for ip in "${CONTROL_PLANE_IP[@]}"; do
  talosctl apply-config --insecure --nodes "$ip" --file _out/controlplane.yaml
done

for ip in "${WORKER_IP[@]}"; do
  talosctl apply-config --insecure --nodes "$ip" --file _out/worker.yaml
done

The control planes remain in the Booting stage until the bootstrap. Once the installation has completed, the ISO drive can be removed from the VMs; the production notes recommend unmounting the installation media so it is unambiguous which disk Talos installs to.

Step 6: Bootstrap the cluster and retrieve the kubeconfig

From now on, talosctl talks to the nodes authenticated through mutual TLS. Set the three control-plane IPs as endpoints, not the VIP: the VIP depends on etcd and kube-apiserver, and if either fails, the Talos API would otherwise be unreachable for recovery.

export TALOSCONFIG=$PWD/_out/talosconfig
talosctl config endpoint "${CONTROL_PLANE_IP[@]}"
talosctl config node "${CONTROL_PLANE_IP[0]}"

# exactly once, on exactly one control-plane node
talosctl bootstrap --nodes "${CONTROL_PLANE_IP[0]}"

talosctl health
talosctl kubeconfig --nodes "${CONTROL_PLANE_IP[0]}"
kubectl get nodes -o wide

talosctl bootstrap initializes etcd. According to the production notes, it runs only once on a single control-plane node; the other control planes join the etcd cluster on their own. Only then does the VIP become active. talosctl kubeconfig merges the credentials into the default kubeconfig. Instead of a shell, talosctl dashboard gives an overview of a node's services, logs and resources.

CNI: Flannel or Cilium

By default, Talos installs Flannel as the CNI in VXLAN mode, with kube-proxy handling service routing. Since Talos 1.13, Flannel can enforce NetworkPolicies; in Talos 1.14 this is enabled through the KubeFlannelCNIConfig document with kubeNetworkPoliciesEnabled: true.

Cilium is the common alternative when eBPF, richer network policies, kube-proxy-free operation or the Gateway API are needed. The decision is made before the bootstrap: the CNI is set to "none" through a patch, in Talos 1.14 by deleting the Flannel document, and Cilium is then installed with Helm.

apiVersion: v1alpha1
kind: KubeFlannelCNIConfig
$patch: delete

For Cilium, Talos already provides the cgroupv2 and bpffs mounts, does not allow workloads to load kernel modules and expects IPAM mode kubernetes; the Cilium guide lists these as fixed prerequisites. For services of type LoadBalancer, a Proxmox cluster additionally needs a solution such as MetalLB or kube-vip; MetalLB vs. kube-vip explains the difference between service load balancing and a control-plane VIP.

Proxmox CSI and cloud controller manager

Two open-source projects connect Kubernetes to the Proxmox layer. Both are maintained by the community, not by Proxmox Server Solutions or Sidero Labs.

• The Proxmox CSI Plugin (version v0.21.0 as of October 2026) creates persistent volumes as VM disks on Proxmox storage and attaches them to the node as block devices. Volumes on local storage such as LVM or ZFS stay bound to their Proxmox host, while volumes on Ceph or NFS can follow pods between hosts. It requires a Proxmox cluster, which may consist of a single node.
• The Proxmox Cloud Controller Manager (version v0.16.1) sets topology.kubernetes.io/region to the Proxmox cluster and topology.kubernetes.io/zone to the hypervisor host, and removes node objects when their VM is deleted. It requires the kubelet to run with --cloud-provider=external. On Talos, this is done with cluster.externalCloudProvider.enabled: true in the machine configuration; the project ships a dedicated manifest for Talos.

With these labels, Kubernetes can spread pods across physical hosts through topology spread constraints or anti-affinity. Whether Proxmox volumes, Longhorn or Rook-Ceph is the right storage layer is compared in Longhorn vs. Rook-Ceph.

ZFS, Ceph and LVM compares local and shared Proxmox storage.

Upgrades: Talos and Kubernetes separately

With Talos, the operating system and Kubernetes have separate lifecycles. A Talos upgrade does not upgrade Kubernetes along with it.

Talos upgrade: talosctl upgrade passes a node the installer image of the target version. Use the same schematic the node was installed with, otherwise the guest agent extension is missing afterwards. Talos uses an A/B scheme and rolls back automatically if the new version fails to boot. By default, the node is drained first. Upgrades are only tested between adjacent minor releases, so the path leads through the latest patch release of every intermediate minor version. We upgrade control planes one at a time so the etcd quorum is preserved throughout.

# first: save an etcd snapshot
talosctl --nodes 192.168.10.11 etcd snapshot etcd-backup.db

talosctl upgrade --nodes 192.168.10.11 \
  --image factory.talos.dev/metal-installer/${SCHEMATIC_ID}:v1.14.4

Kubernetes upgrade: talosctl upgrade-k8s upgrades all Kubernetes components in the cluster, even though --nodes addresses only one control-plane node. A dry run shows the plan and deprecated API resources up front.

talosctl --nodes 192.168.10.11 upgrade-k8s --to 1.37.1 --dry-run
talosctl --nodes 192.168.10.11 upgrade-k8s --to 1.37.1

Proxmox snapshots of the VMs replace neither etcd snapshots nor application backups. The four backup layers are described in Kubernetes backup and restore.

Common mistakes

• VirtIO SCSI Single as controller: the bootstrap hangs or disks are not discovered. Use VirtIO SCSI.
• CPU type kvm64: Talos images for amd64 require x86-64-v2. According to the system requirements, an older CPU model halts at boot with "x86_64 microarchitecture level 2 or higher is required".
• Ballooning enabled: Talos does not see all of the assigned memory.
• Guest agent without the extension: if the QEMU guest agent is enabled in Proxmox but the image was built without siderolabs/qemu-guest-agent, it only produces log spam.
• VIP as talosctl endpoint: during an etcd problem, the Talos API becomes unreachable.
• All control planes on one host: three VMs only provide high availability when they run on three physical hosts.
• Changing DHCP addresses: without reservations or a static configuration, node IPs change and talosconfig endpoints point nowhere.

Outlook: Terraform and OpenTofu

For reproducible clusters, the entire flow can be expressed as code. The siderolabs/talos provider (v0.12.0 as of October 2026) models Image Factory schematics, secrets, machine configuration, apply-config, bootstrap and kubeconfig as resources and data sources. The community provider bpg/proxmox (v0.117.0) creates the VMs in Proxmox VE. Both are also available in the OpenTofu registry. Together they form a chain of VM creation, configuration and bootstrap, followed by GitOps for CNI, CSI and workloads.

Alternatively, Talos accepts the machine configuration through the nocloud mechanism, for example via a cloud-init drive or the SMBIOS serial number in Proxmox. This removes the manual apply-config in maintenance mode.

The follow-up guide Automate Talos on Proxmox with OpenTofu covers VM declarations, machine configuration, bootstrap and state handling as one workflow.

How WZ-IT works

For Kubernetes on Proxmox, we design infrastructure and cluster together:

1. Sizing and failure domains: workloads, availability targets and growth determine the number and size of Proxmox hosts and node VMs.
2. Proxmox design: compute, storage, network segments, quorum and backup architecture are defined before the first Talos VM exists.
3. Automated cluster build: node VMs, machine configuration and the platform baseline are created reproducibly as code, extended with GitOps from platform engineering.
4. Onboarding and lifecycle: applications are migrated in a controlled way, upgrades of Proxmox, Talos and Kubernetes are coordinated and documented, and ongoing operations are available as managed Kubernetes.

The distribution follows the operating model. Talos Linux fits when a declaratively managed, minimal node base is wanted; for other requirements, k3s or RKE2 are options.

Further guides

• Kubernetes on Proxmox: architecture, VM or LXC, high availability on two layers, storage and backup.
• k3s vs. RKE2 vs. Talos: which distribution fits which operating model.
• MetalLB vs. kube-vip: service load balancing on bare metal and Proxmox.
• Longhorn vs. Rook-Ceph: Kubernetes-native storage layers compared.
• Access Kubernetes privately with NetBird: cluster API and Talos API without public exposure.
• Proxmox: LXC vs. KVM: when to use containers and when VMs.

To plan, build or operate a Talos cluster on Proxmox: Kubernetes on Proxmox with WZ-IT.

For the operating model, see What is Talos Linux?.

Sources

• Talos Linux: Proxmox installation guide (v1.14)

• Talos Linux: production notes

• Talos Linux: system requirements and support matrix

• Talos Linux: Image Factory

• Talos Linux: Virtual (shared) IP

• Talos Linux: Upgrading Talos and Upgrading Kubernetes

• Talos Linux: talosctl CLI reference

• Talos Linux: Flannel and Cilium

• Talos Linux: design philosophy

• Talos Linux v1.14.4 release notes

• Proxmox VE: qm manual and High Availability

• Proxmox VE: Linux Container

• Proxmox CSI Plugin and Proxmox Cloud Controller Manager

• Terraform provider siderolabs/talos and bpg/proxmox

• Talos MPL-2.0

• Proxmox CSI v0.21.0

• bpg/proxmox v0.117.0