> ## 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.

# External Volumes

> Configuring external volumes to mount hypervisor-provisioned storage in Talos Linux.

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 />

External volumes allow mounting volumes that were created outside of Talos, over the hypervisor or network.
Unlike [user volumes](./user) which provision new storage from Talos-managed disks, or [existing volumes](./existing) which mount pre-existing partitions, external volumes are provisioned and managed by the hypervisor.

External volumes are mounted under `/var/mnt/<name>`.

Virtiofs is a shared file system that lets virtual machines access a directory tree on the host.
Unlike other approaches, it is designed to offer local file system semantics and performance.

Virtiofs uses [FUSE](https://github.com/libfuse/libfuse) as the foundation.
Unlike traditional FUSE where the file system daemon runs in userspace, the virtiofs daemon runs on the host.
A [VIRTIO](https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=virtio) device carries FUSE messages and provides extensions for advanced features.

Virtiofs is available in mainline Linux since version 5.4, QEMU 5.0, and libvirt 6.2.

## Requirements

External volumes require Talos to run inside a virtual machine with virtiofs support from the hypervisor.
The following hypervisors are supported:

* QEMU
* libvirt
* Proxmox VE
* Other hypervisors that support virtiofs

> Note: External volumes are not available on bare metal machines.

### Create external volumes

To create an external volume, append the following [document](../../../reference/configuration/block/externalvolumeconfig) to the machine configuration:

```yaml theme={null}
# external-volume.patch.yaml
apiVersion: v1alpha1
kind: ExternalVolumeConfig
name: virtiofs-data
filesystemType: virtiofs
mount:
  virtiofs:
    tag: Data
```

For example, this machine configuration patch can be applied using the following command:

```bash theme={null}
talosctl --nodes <NODE> patch mc --patch @external-volume.patch.yaml
```

In this example, an external volume named `virtiofs-data` is created, which will be mounted at `/var/mnt/virtiofs-data` on the node.

The status of the volume can be checked using the following command:

```bash theme={null}
$ talosctl get volumestatus x-virtiofs-data # note x- prefix
NODE         NAMESPACE   TYPE           ID              VERSION   TYPE       PHASE   LOCATION   SIZE
172.20.0.5   runtime     VolumeStatus   x-virtiofs-data 2         external   ready   Data
```

The disk is immediately mounted to `/var/mnt/virtiofs-data`.

### Remove external volumes

Before removing an external volume, ensure that it is not used anymore.

In order to remove an external volume, first remove the configuration document from the machine configuration.
The `VolumeStatus` resource will be removed automatically by Talos Linux.

> Note: The actual disk data hasn't been removed yet, so you can re-apply the external volume configuration back and the volume will be available again.
> To remove the disk data, you need to remove it from the virtual machine host manually.