Skip to content

Commit 4092d46

Browse files
committed
docs: add documentation about virtiofs volumes
Add documentation about new `ExternealVolumeConfig`, with focus on the `virtiofs` type. Signed-off-by: Mateusz Urbanek <mateusz.urbanek@siderolabs.com>
1 parent 0a7ded3 commit 4092d46

1 file changed

Lines changed: 78 additions & 0 deletions

File tree

  • public/talos/v1.13/configure-your-talos-cluster/storage-and-disk-management/disk-management
Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
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

Comments
 (0)