Skip to content

Commit 0f1157a

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 0f1157a

1 file changed

Lines changed: 80 additions & 0 deletions

File tree

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

0 commit comments

Comments
 (0)