> ## Documentation Index
> Fetch the complete documentation index at: https://docs.siderolabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Proxmox

> Creating Talos Kubernetes cluster using Proxmox.

export const release_v1_13 = 'v1.13.5';

export const VersionWarningBanner = () => {
  const latestVersion = "v1.13";
  const [latestUrl, setLatestUrl] = useState(null);
  const [currentVersion, setCurrentVersion] = useState(null);
  const [isBeta, setIsBeta] = useState(false);
  const parseVersion = v => v.replace("v", "").split(".").map(Number);
  const isGreaterVersion = (a, b) => {
    const [aMajor, aMinor] = parseVersion(a);
    const [bMajor, bMinor] = parseVersion(b);
    if (aMajor > bMajor) return true;
    if (aMajor === bMajor && aMinor > bMinor) return true;
    return false;
  };
  useEffect(() => {
    if (typeof window === "undefined") return;
    const {pathname, hash, search} = window.location;
    const match = pathname.match(/\/talos\/(v\d+\.\d+)\//);
    if (!match) return;
    const detectedVersion = match[1];
    if (detectedVersion === latestVersion) return;
    setCurrentVersion(detectedVersion);
    if (isGreaterVersion(detectedVersion, latestVersion)) {
      setIsBeta(true);
    }
    const newPath = pathname.replace(`/talos/${detectedVersion}/`, `/talos/${latestVersion}/`);
    setLatestUrl(`${newPath}${search}${hash}`);
  }, []);
  if (!latestUrl || !currentVersion) return null;
  return <div className="not-prose sticky top-6 z-50 my-6">
      <div className="border border-yellow-500/30 bg-yellow-500/10 px-4 py-3 rounded-xl">
        <div className="text-sm">
          {isBeta ? <>
              ⚠️ You are viewing a <strong>beta version</strong> of Talos ({currentVersion}).
              This version may be unstable.
              <a href={latestUrl} className="ml-2 underline text-yellow-400 hover:text-yellow-300 font-medium">
                View latest stable version {latestVersion} →
              </a>
            </> : <>
              ⚠️ You are viewing an older version of Talos ({currentVersion}).
              <a href={latestUrl} className="ml-2 underline text-yellow-400 hover:text-yellow-300 font-medium">
                View the latest version {latestVersion} →
              </a>
            </>}
        </div>
      </div>
    </div>;
};

<VersionWarningBanner />

In this guide you will create a Kubernetes cluster on Proxmox, from uploading the Talos ISO to bootstrapping etcd and retrieving your kubeconfig. Follow the steps in order — each one builds on the last.

## Video walkthrough

To see a live demo of this guide, visit Youtube here:

<iframe width="560" height="315" src="https://www.youtube.com/embed/MyxigW4_QFM" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen />

## Prerequisites

Before you begin, make sure the following are in place. The QEMU guest agent section is optional, only follow it if you need guest VM shutdown support.

* **Proxmox**: This guide assumes you have already installed Proxmox on the server where you want to create Talos VMs. Visit the [Proxmox downloads page](https://www.proxmox.com/en/downloads) if you haven't done this yet.

* **talosctl**: Install `talosctl` on macOS or Linux with:

  ```bash theme={null}
  brew install siderolabs/tap/talosctl
  ```

  For manual installation and other platforms, see the [talosctl installation guide](../../getting-started/talosctl).

* **ISO image**: Download the Talos ISO from [Image Factory](https://www.talos.dev/latest/talos-guides/install/boot-assets/#image-factory) with this command:

  ```bash theme={null}
  mkdir -p _out/
  curl https://factory.talos.dev/image/376567988ad370138ad8b2698212367b8edcb69b5fd68c80be1f2ec7d603b4ba/<version>/metal-<arch>.iso -L -o _out/metal-<arch>.iso
  ```

  For example version, for linux platform:

  <CodeBlock lang="sh">
    {`mkdir -p _out/\ncurl https://factory.talos.dev/image/376567988ad370138ad8b2698212367b8edcb69b5fd68c80be1f2ec7d603b4ba/${release_v1_13}/metal-amd64.iso -L -o _out/metal-amd64.iso`}
  </CodeBlock>

### Optional: QEMU guest agent ISO

QEMU guest agent support for guest VM shutdowns requires a custom ISO and installer image. Skip this section if that doesn't apply to you.

1. **Build the custom ISO**: Go to the [Image Factory](https://factory.talos.dev/) and complete these steps to build a custom ISO:
   * Select your Talos version
   * Check the box for `siderolabs/qemu-guest-agent` and submit. This action will provide you with a link similar to:
     <CodeBlock lang="sh">
       {`Metal ISO\n\namd64 ISO\n    https://factory.talos.dev/image/ce4c980550dd2ab1b17bbf2b08801c7eb59418eafe8f279833297925d67c7515/${release_v1_13}/metal-amd64.iso\narm64 ISO\n    https://factory.talos.dev/image/ce4c980550dd2ab1b17bbf2b08801c7eb59418eafe8f279833297925d67c7515/${release_v1_13}/metal-arm64.iso\n\nInstaller Image\n\nFor the initial Talos install or upgrade, use the following installer image:\nfactory.talos.dev/installer/ce4c980550dd2ab1b17bbf2b08801c7eb59418eafe8f279833297925d67c7515:${release_v1_13}`}
     </CodeBlock>
   * Download the above ISO and take note of the installer image URL, you will need it later

2. **Enable QEMU Guest Agent in Proxmox:** Once your VM is created, go to **VM → Options** and set **QEMU Guest Agent** to **Enabled**.

<Warning> Only enable QEMU Guest Agent in Proxmox if you built the ISO with the `siderolabs/qemu-guest-agent` extension. Enabling it without the extension will only generate log spam and provide no functionality. See [Image Factory](../../learn-more/image-factory) for more on building custom ISOs.</Warning>

### VM resource requirements

Before creating VMs, familiarise yourself with the [system requirements](../../getting-started/system-requirements) for Talos and use the following as a baseline for all Talos nodes on Proxmox:

| Setting             | Recommended value                    | Notes                                                                                                                   |
| ------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| **BIOS**            | `ovmf` (UEFI)                        | Modern firmware, Secure Boot support, better hardware compatibility                                                     |
| **Machine**         | `q35`                                | Modern PCIe-based machine type with better device support                                                               |
| **CPU type**        | `host`                               | Enables advanced instruction sets (AVX-512, etc.). Use `kvm64` with feature flags for Proxmox \< 8.0                    |
| **CPU cores**       | 2+ (control plane), 4+ (workers)     | Minimum 2 cores required                                                                                                |
| **Memory**          | 4GB+ (control plane), 8GB+ (workers) | Minimum 2GB required                                                                                                    |
| **Disk controller** | VirtIO SCSI                          | Do NOT use **VirtIO SCSI Single** — causes bootstrap hangs ([#11173](https://github.com/siderolabs/talos/issues/11173)) |
| **Disk format**     | Raw or QCOW2                         | Raw preferred for performance; QCOW2 for snapshots                                                                      |
| **Disk cache**      | Write Through                        | Use None for clustered environments                                                                                     |
| **Network model**   | `virtio`                             | Paravirtualized driver, best performance (up to 10 Gbit)                                                                |
| **EFI disk**        | 4MB                                  | Required for UEFI firmware, stores Secure Boot keys                                                                     |
| **Ballooning**      | Disabled                             | Talos does not support memory hotplug                                                                                   |
| **RNG device**      | VirtIO RNG (optional)                | Better entropy for cryptographic operations                                                                             |

## Step 1: Upload the ISO

From the Proxmox UI, select the **local** storage and enter the **Content** section. Click the **Upload** button:

<img src="https://mintcdn.com/siderolabs-fe86397c/hVMyOt-W9fmKR5ik/talos/v1.13/platform-specific-installations/virtualized-platforms/images/proxmox-click-upload.png?fit=max&auto=format&n=hVMyOt-W9fmKR5ik&q=85&s=26e0b7fa4bb3b74b005bd530e6193203" width="500px" data-path="talos/v1.13/platform-specific-installations/virtualized-platforms/images/proxmox-click-upload.png" />

Select the ISO you downloaded in the prerequisites, then click **Upload**:

<img src="https://mintcdn.com/siderolabs-fe86397c/hVMyOt-W9fmKR5ik/talos/v1.13/platform-specific-installations/virtualized-platforms/images/proxmox-select-iso.png?fit=max&auto=format&n=hVMyOt-W9fmKR5ik&q=85&s=eab6c14d4491812ec144d6f31b3f329c" width="500px" data-path="talos/v1.13/platform-specific-installations/virtualized-platforms/images/proxmox-select-iso.png" />

## Step 2: Create VMs

Create a new VM by clicking **Create VM** in the Proxmox UI:

<img src="https://mintcdn.com/siderolabs-fe86397c/hVMyOt-W9fmKR5ik/talos/v1.13/platform-specific-installations/virtualized-platforms/images/proxmox-create-vm.png?fit=max&auto=format&n=hVMyOt-W9fmKR5ik&q=85&s=6bea77c84dce0678cdb06367f934a53a" width="500px" data-path="talos/v1.13/platform-specific-installations/virtualized-platforms/images/proxmox-create-vm.png" />

This action will open 8 tabs, configure the tabs as follows:

* **Name tab**: Fill out a name for the VM:

<img src="https://mintcdn.com/siderolabs-fe86397c/hVMyOt-W9fmKR5ik/talos/v1.13/platform-specific-installations/virtualized-platforms/images/proxmox-edit-vm-name.png?fit=max&auto=format&n=hVMyOt-W9fmKR5ik&q=85&s=b022671c7e769a0f5655498ddc6ad056" width="500px" data-path="talos/v1.13/platform-specific-installations/virtualized-platforms/images/proxmox-edit-vm-name.png" />

* **OS tab**: Select the ISO uploaded in Step 1:

<img src="https://mintcdn.com/siderolabs-fe86397c/hVMyOt-W9fmKR5ik/talos/v1.13/platform-specific-installations/virtualized-platforms/images/proxmox-edit-os.png?fit=max&auto=format&n=hVMyOt-W9fmKR5ik&q=85&s=44f7314f76ec0870e9d0aac5e06dcb5e" width="500px" data-path="talos/v1.13/platform-specific-installations/virtualized-platforms/images/proxmox-edit-os.png" />

* **System tab:**
  * Set **BIOS** to `ovmf` (UEFI)
  * Set **Machine** to `q35`
  * Add an **EFI Disk** (4MB) for persistent UEFI settings and Secure Boot key storage

* **Hard Disk tab:**
  * Set **Bus/Device** to `VirtIO SCSI` (NOT **VirtIO SCSI Single**)
  * Set **Storage** to your main storage pool
  * Set **Format** to `Raw` (performance) or `QCOW2` (snapshots)
  * Set **Cache** to `Write Through`, or `None` for clustered environments
  * Enable **Discard** and **SSD emulation** if using SSD storage

* **CPU tab:**

  * Set **Cores** to 2+ for control planes, 4+ for workers
  * Set **Type** to `host` for best performance

  For Proxmox \< 8.0, use `kvm64` with feature flags instead. Add the following to `/etc/pve/qemu-server/<vmid>.conf`:

  ```text theme={null}
  args: -cpu kvm64,+cx16,+lahf_lm,+popcnt,+sse3,+ssse3,+sse4.1,+sse4.2
  ```

  > **Note:** `host` CPU type prevents live VM migration.

<img src="https://mintcdn.com/siderolabs-fe86397c/hVMyOt-W9fmKR5ik/talos/v1.13/platform-specific-installations/virtualized-platforms/images/proxmox-edit-cpu.png?fit=max&auto=format&n=hVMyOt-W9fmKR5ik&q=85&s=736ae4ee3e1c17c82d9fcbbce890087d" width="500px" data-path="talos/v1.13/platform-specific-installations/virtualized-platforms/images/proxmox-edit-cpu.png" />

* **Memory tab:**

  * Set **Memory** to 4GB+ for control planes, 8GB+ for workers
  * **Disable Ballooning** — Talos does not support memory hotplug, and enabling it will prevent Talos from seeing all available memory

  <img src="https://mintcdn.com/siderolabs-fe86397c/hVMyOt-W9fmKR5ik/talos/v1.13/platform-specific-installations/virtualized-platforms/images/proxmox-edit-ram.png?fit=max&auto=format&n=hVMyOt-W9fmKR5ik&q=85&s=389a45d2e83819c7169f54c3d0678cfd" width="500px" data-path="talos/v1.13/platform-specific-installations/virtualized-platforms/images/proxmox-edit-ram.png" />

* **Network tab:**

  * Set **Model** to `virtio`
  * Set **Bridge** to your network bridge (e.g., `vmbr0`)

  <img src="https://mintcdn.com/siderolabs-fe86397c/hVMyOt-W9fmKR5ik/talos/v1.13/platform-specific-installations/virtualized-platforms/images/proxmox-edit-nic.png?fit=max&auto=format&n=hVMyOt-W9fmKR5ik&q=85&s=f8506479e079edb5dcd1bbd281b1c5b6" width="500px" data-path="talos/v1.13/platform-specific-installations/virtualized-platforms/images/proxmox-edit-nic.png" />

<Note>Enable a serial console (`ttyS0`) in Proxmox VM settings to see early boot logs and troubleshoot network issues. This is especially useful when debugging DHCP timing or bridge configuration problems.</Note>

* **Confirm tab**: Finish creating the VM by clicking through the **Confirm** tab and then **Finish**.

Repeat this process for each additional node, at minimum one control plane and one worker.

## Step 3: Start the control plane node

Start the VM designated as the first control plane node. It will boot from the ISO and enter maintenance mode.

<Tabs>
  <Tab title="With DHCP">
    Once the machine enters maintenance mode, the console will display the IP address the node received. Take note of this IP — it will be referred to as `$CONTROL_PLANE_IP` for the rest of this guide:

    ```bash theme={null}
    export CONTROL_PLANE_IP=1.2.3.4
    ```

    <img src="https://mintcdn.com/siderolabs-fe86397c/hVMyOt-W9fmKR5ik/talos/v1.13/platform-specific-installations/virtualized-platforms/images/proxmox-maintenance-mode.png?fit=max&auto=format&n=hVMyOt-W9fmKR5ik&q=85&s=79e8999d9e9d9baf6f592dc13741fb9c" width="500px" data-path="talos/v1.13/platform-specific-installations/virtualized-platforms/images/proxmox-maintenance-mode.png" />
  </Tab>

  <Tab title="Without DHCP">
    To apply machine configuration in maintenance mode, the VM needs a static IP. Set it manually at boot time.

    1. Press `e` at the GRUB menu:

    <img src="https://mintcdn.com/siderolabs-fe86397c/hVMyOt-W9fmKR5ik/talos/v1.13/platform-specific-installations/virtualized-platforms/images/proxmox-maintenance-mode-grub-menu.png?fit=max&auto=format&n=hVMyOt-W9fmKR5ik&q=85&s=683449790defd3764cb7fc8332e6ada2" width="600px" data-path="talos/v1.13/platform-specific-installations/virtualized-platforms/images/proxmox-maintenance-mode-grub-menu.png" />

    2. Append the IP parameters to the boot line using the following format ([kernel nfsroot format](https://www.kernel.org/doc/Documentation/filesystems/nfs/nfsroot.txt)):

    ```bash theme={null}
    ip=<client-ip>:<srv-ip>:<gw-ip>:<netmask>:<host>:<device>:<autoconf>
    ```

    For example, with `$CONTROL_PLANE_IP` as `192.168.0.100` and gateway `192.168.0.1`:

    ```bash theme={null}
    linux /boot/vmlinuz init_on_alloc=1 slab_nomerge pti=on panic=0 consoleblank=0 printk.devkmsg=on earlyprintk=ttyS0 console=tty0 console=ttyS0 talos.platform=metal ip=192.168.0.100::192.168.0.1:255.255.255.0::eth0:off
    ```

    <img src="https://mintcdn.com/siderolabs-fe86397c/hVMyOt-W9fmKR5ik/talos/v1.13/platform-specific-installations/virtualized-platforms/images/proxmox-maintenance-mode-grub-menu-ip.png?fit=max&auto=format&n=hVMyOt-W9fmKR5ik&q=85&s=91931c30efc935171e77d13637cd083b" width="630px" data-path="talos/v1.13/platform-specific-installations/virtualized-platforms/images/proxmox-maintenance-mode-grub-menu-ip.png" />

    3. Press `Ctrl-x` or `F10` to boot with the updated parameters.
  </Tab>
</Tabs>

## Step 4: Generate machine configurations

With `$CONTROL_PLANE_IP` set, generate the machine configurations for your cluster.

Choose the tab that matches your ISO.

<Tabs>
  <Tab title="Talos ISO">
    ```bash theme={null}
    talosctl gen config talos-proxmox-cluster https://$CONTROL_PLANE_IP:6443 --output-dir _out
    ```
  </Tab>

  <Tab title="QEMU guest agent ISO">
    Use this if you built the custom ISO with the `siderolabs/qemu-guest-agent` extension in the prerequisites. The command is the same but passes the custom installer image URL you noted earlier.

    <CodeBlock lang="sh">
      {`talosctl gen config talos-proxmox-cluster https://$CONTROL_PLANE_IP:6443 --output-dir _out --install-image factory.talos.dev/installer/ce4c980550dd2ab1b17bbf2b08801c7eb59418eafe8f279833297925d67c7515:${release_v1_13}`}
    </CodeBlock>
  </Tab>
</Tabs>

This command creates three files in `_out/`: `controlplane.yaml`, `worker.yaml`, and `talosconfig`.

<Note>
  The default config installs Talos to `/dev/sda`. Depending on your setup, the virtual disk may be at a different path (e.g., `/dev/vda`). Check available disks with:

  ```bash theme={null}
  talosctl get disks --insecure --nodes $CONTROL_PLANE_IP
  ```

  Update `install.disk` in `controlplane.yaml` and `worker.yaml` if needed.
</Note>

## Step 5: Apply configuration to the control plane

Apply the control plane configuration to the node. If you are setting up an HA control plane, repeat this step for each additional control plane node.

```bash theme={null}
talosctl apply-config --insecure --nodes $CONTROL_PLANE_IP --file _out/controlplane.yaml
```

You should see activity in the Proxmox console. Talos will install to disk, the VM will reboot, and Talos will configure the Kubernetes control plane. The VM will remain in stage `Booting` until the cluster is bootstrapped in the next steps.

## Step 6: Apply configuration to worker nodes

Start each worker VM and wait for it to enter maintenance mode. Repeat this step for each worker node, substituting `$WORKER_IP` with each node's IP address.

```bash theme={null}
talosctl apply-config --insecure --nodes $WORKER_IP --file _out/worker.yaml
```

## Step 7: Bootstrap the cluster

With the control plane and worker nodes configured, complete the cluster setup by running the following commands in order:

1. Configure talosctl to talk to your control plane node:

```bash theme={null}
export TALOSCONFIG="_out/talosconfig"
talosctl config endpoint $CONTROL_PLANE_IP
talosctl config node $CONTROL_PLANE_IP
```

2. Bootstrap etcd:

```bash theme={null}
talosctl bootstrap
```

3. Retrieve the kubeconfig:

```bash theme={null}
talosctl kubeconfig .
```

4. Verify that your cluster is ready:

```bash theme={null}
kubectl get nodes
```

## Troubleshooting

This section covers common issues you may encounter when setting up Talos VMs on Proxmox, along with steps to resolve them.

### Cluster creation issues

If `talosctl cluster create` fails with disk controller errors, the most likely cause is an unsupported disk controller type. For example:

* `virtio-scsi-single disk controller is not supported`: This disk controller type causes Talos bootstrap to hang. Use `virtio` or `scsi` instead:

  ```bash theme={null}
  # Wrong - will be rejected
  talosctl cluster create --disks virtio-scsi-single:10GiB

  # Correct - use virtio or scsi
  talosctl cluster create --disks virtio:10GiB
  talosctl cluster create --disks scsi:10GiB
  ```

### Network connectivity issues

If nodes fail to obtain IP addresses or show "network is unreachable" errors, work through the following checks:

1. **Verify bridge interface**: Ensure the bridge interface (e.g., `vmbr0`) exists and is UP before starting VMs:

```bash theme={null}
ip link show vmbr0
```

2. **Check DHCP server**: Ensure DHCP server is running and reachable from the bridge network

3. **Firewall rules**: If Proxmox VM firewall is enabled, allow DHCP traffic (UDP ports 67/68).
   If you enforce further filtering, ensure control-plane/API connectivity per your environment's policy (see Talos networking docs).

4. **VLAN configuration**: Ensure VLAN tags match between bridge configuration, VM network settings, and switch configuration

5. **Serial console**: Enable serial console to view early boot logs and network initialization messages

### Disk controller issues

If you run into disk-related problems during setup, the following may help:

* **Configuration rejected**: If you see "virtio-scsi-single disk controller is not supported", use `--disks virtio:10GiB` instead of `--disks virtio-scsi-single:10GiB`
* **Bootstrap hangs**: If bootstrap hangs or disks aren't discovered, verify you're using **VirtIO SCSI** (not "VirtIO SCSI Single")
* **Disk not found**: Check disk path using `talosctl get disks --insecure --nodes $CONTROL_PLANE_IP` and update `install.disk` in machine config if needed (e.g., `install.disk: /dev/vda`)

### Secure boot

For Secure Boot setup, see the [Secure Boot documentation](../bare-metal-platforms/secureboot).

## Cleaning up

To cleanup, simply stop and delete the virtual machines from the Proxmox UI.