Skip to main content
User Volumes allow to treat available disk space as a pool of allocatable resource, which can be dynamically allocated to different applications. The user volumes are supposed to be used mostly for hostPath mounts in Kubernetes, but they can be used for other purposes as well. When a user volume configuration is applied, Talos Linux will either locate an existing volume or provision a new one. The volume will be created on the disk which satisfies the diskSelector expression and has enough free space to satisfy the minSize requirement. The user volume is identified by a unique name, which is used both as a mount location and as a label for the volume. The volume name must be unique across all user volumes, and it should be between 1 and 34 characters long, and can only contain ASCII letters, digits, and - (dash) characters. The volume label is derived from the volume name as u-<volume-name>, and it is used to identify the volume on the disk after initial provisioning. The volume mount location is /var/mnt/<volume-name>, and it gets automatically propagated into the kubelet container to provide additional features like subPath mounts. Disk encryption can be optionally enabled for user volumes.

​
Create user volumes

To create a user volume, append the following document to the machine configuration:
For example, this machine configuration patch can be applied using the following command:
In this example, a user volume named local-volume is created on the first NVMe disk which has 100GB of disk space available, and it will be created as maximum of 200GB if that space is available. The status of the volume can be checked using the following command:
If the volume fails to be provisioned, use the -o yaml flag to get additional details. The volume is immediately mounted to /var/mnt/local-volume:
It can be used in a Kubernetes pod as a hostPath mount:
Please note, the path inside the container can be different from the path on the host.

​
Remove user volumes

Before removing a user volume, ensure that it is not mounted in any Kubernetes pod. In order to remove a user volume, first remove the configuration document from the machine configuration. The VolumeStatus and MountStatus resources will be removed automatically by Talos Linux.
Note: The actual disk data hasn’t been removed yet, so you can re-apply the user volume configuration back and it will be re-provisioned on the same disk.
To wipe the disk data, and make it allocatable again, use the following command:
The nvme0n1p2 is the partition name, and it can be obtained from the VolumeStatus resource before the user volume is removed, or from the DiscoveredVolume resource any time later.
Note: If the wipe disk command fails with blockdevice is in use by volume, it means the user volume has not been removed from the machine configuration.

​
Types of user volumes

UserVolumeConfig includes an optional volumeType field that controls how a user volume is created and managed. If omitted, the system defaults to partition. Types disk and directory are advanced options with specific use cases. If unsure, use the default partition type.

​
volumeType: partition (default)

A standard volume backed by a dedicated partition on the underlying storage device. If you are unsure which type to choose, this is the recommended option.

​
volumeType: disk

It is primarily intended for scenarios where you want to dedicate a whole disk to a single workload without partitioning - for example, when provisioning on top of LVM logical volumes or other block devices that do not support partitioning. When set to disk, the volume is provisioned from an entire block device rather than a partition. If you want to consume the entire disk with partitioning support, use a partition user volume instead and set grow: true without specifying maxSize. When using volumeType: disk, the disk itself is not labeled or partitioned. The disk selector must uniquely and stably identify the device (for example via WWN, serial, or persistent path). If the selector is ambiguous, a different device may be selected after a reboot. Restrictions for disk volumes:
  • The provisioning block must not define size-related settings (minSize, maxSize, or grow). A full device implies a fixed size.

​
User volumes on LVM logical volumes

An LVM logical volume can back a user volume. Use volumeType: disk so Talos treats the logical volume as the block device for the user volume instead of trying to create another partition on it. First create the LVMVolumeGroupConfig and LVMLogicalVolumeConfig. For example, create a logical volume that uses the full volume group:
After the logical volume is created, find its stable device symlink. The logical volume appears as a device-mapper disk with symlinks such as /dev/mapper/vg--pool-lv--user or /dev/disk/by-dm-name/vg--pool-lv--user.
Then create a UserVolumeConfig of type disk and match that symlink:
Apply the user volume configuration:
Talos formats the logical volume, mounts it at /var/mnt/lvm-user, and propagates the mount into the kubelet container. Check readiness with the standard volume and mount resources:
When matching an LVM logical volume, use a stable symlink from disk.symlinks instead of matching /dev/dm-* directly. Device-mapper numbers can change across boots.

​
volumeType: directory

This type is useful for lightweight storage needs where full partitioning is unnecessary or impractical, and all that is required is a simple directory on the EPHEMERAL volume. When set to directory, the system bypasses provisioning and filesystem creation. Instead, it creates a host directory at:
Characteristics and limitations of directory volumes:
  • No provisioning, filesystem operations, or encryption are performed.
  • The volume is simply a directory on the EPHEMERAL volume.
  • This type provides minimal overhead but does not deliver filesystem-level isolation.
  • Storage capacity is limited by the host’s EPHEMERAL partition.
  • Not suitable for workloads that require predictable or enforceable storage quotas.