|
| 1 | +--- |
| 2 | +title: "External Volumes" |
| 3 | +description: "Configuring external volumes to mount hypervisor-provisioned storage in Talos Linux." |
| 4 | +weight: 60 |
| 5 | +--- |
| 6 | + |
| 7 | +import { VersionWarningBanner } from "/snippets/version-warning-banner.jsx" |
| 8 | + |
| 9 | +<VersionWarningBanner /> |
| 10 | + |
| 11 | +External volumes allow mounting volumes that were created outside of Talos, over the hypervisor or network. |
| 12 | +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. |
| 13 | + |
| 14 | +External volumes are mounted under `/var/mnt/<name>`. |
| 15 | + |
| 16 | +Virtiofs is a shared file system that lets virtual machines access a directory tree on the host. |
| 17 | +Unlike other approaches, it is designed to offer local file system semantics and performance. |
| 18 | + |
| 19 | +Virtiofs uses [FUSE](https://github.com/libfuse/libfuse) as the foundation. |
| 20 | +Unlike traditional FUSE where the file system daemon runs in userspace, the virtiofs daemon runs on the host. |
| 21 | +A [VIRTIO](https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=virtio) device carries FUSE messages and provides extensions for advanced features. |
| 22 | + |
| 23 | +Virtiofs is available in mainline Linux since version 5.4, QEMU 5.0, and libvirt 6.2. |
| 24 | + |
| 25 | +## Requirements |
| 26 | + |
| 27 | +External volumes require Talos to run inside a virtual machine with virtiofs support from the hypervisor. |
| 28 | +The following hypervisors are supported: |
| 29 | + |
| 30 | +- QEMU |
| 31 | +- libvirt |
| 32 | +- Proxmox VE |
| 33 | +- Other hypervisors that support virtiofs |
| 34 | + |
| 35 | +> Note: External volumes are not available on bare metal machines. |
| 36 | +
|
| 37 | +### Create external volumes |
| 38 | + |
| 39 | +To create an external volume, append the following [document](../../../reference/configuration/block/externalvolumeconfig) to the machine configuration: |
| 40 | + |
| 41 | +```yaml |
| 42 | +# external-volume.patch.yaml |
| 43 | +apiVersion: v1alpha1 |
| 44 | +kind: ExternalVolumeConfig |
| 45 | +name: virtiofs-data |
| 46 | +filesystemType: virtiofs |
| 47 | +mount: |
| 48 | + virtiofs: |
| 49 | + tag: Data |
| 50 | +``` |
| 51 | +
|
| 52 | +For example, this machine configuration patch can be applied using the following command: |
| 53 | +
|
| 54 | +```bash |
| 55 | +talosctl --nodes <NODE> patch mc --patch @external-volume.patch.yaml |
| 56 | +``` |
| 57 | + |
| 58 | +In this example, an external volume named `virtiofs-data` is created, which will be mounted at `/var/mnt/virtiofs-data` on the node. |
| 59 | + |
| 60 | +The status of the volume can be checked using the following command: |
| 61 | + |
| 62 | +```bash |
| 63 | +$ talosctl get volumestatus x-virtiofs-data # note x- prefix |
| 64 | +NODE NAMESPACE TYPE ID VERSION TYPE PHASE LOCATION SIZE |
| 65 | +172.20.0.5 runtime VolumeStatus x-virtiofs-data 2 external ready Data |
| 66 | +``` |
| 67 | + |
| 68 | +The disk is immediately mounted to `/var/mnt/virtiofs-data`. |
| 69 | + |
| 70 | +### Remove external volumes |
| 71 | + |
| 72 | +Before removing an external volume, ensure that it is not used anymore. |
| 73 | + |
| 74 | +In order to remove an external volume, first remove the configuration document from the machine configuration. |
| 75 | +The `VolumeStatus` resource will be removed automatically by Talos Linux. |
| 76 | + |
| 77 | +> 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. |
| 78 | +> To remove the disk data, you need to remove it from the virtual machine host manually. |
0 commit comments