Create a Storage Pool

A storage pool is where a host keeps the writable disks of its virtual machines. The pool is declared in the machine configuration with a StoragePool document, and Talos creates it in libvirt as a directory on a Talos volume. This page shows how to create a storage pool, check its status, and change or remove it. The host needs the libvirtd system extension, whose ext-virtstoraged service manages storage pools. To install it, see Install a hypervisor host. In the commands on this page, replace <host-ip> with the IP address of the host.

​

Create a storage pool

A storage pool is stored on a Talos volume. The volume is declared in its own document, using one of these types:

• A UserVolumeConfig, for a directory, partition, or disk on the host.
• An ExistingVolumeConfig, for a volume that already exists on the host.
• An ExternalVolumeConfig, for a volume mounted from outside the host, such as an NFS export. NFS support was added in Talos Linux v1.15.

The volume has two requirements:

• It must be writable and have a filesystem.
• It can back only one storage pool. Each storage pool and each content library needs its own volume.

Talos stores the pool in a directory with the pool’s name, inside the volume. The following steps create a storage pool on a directory volume and check that it is ready.

1. Run the following command to create storage-pool.yaml, which declares a directory volume named vm-disks and a storage pool named pool1 that uses it:
   cat <<'EOF' > storage-pool.yaml
   apiVersion: v1alpha1
   kind: UserVolumeConfig
   name: vm-disks
   volumeType: directory
   ---
   apiVersion: v1alpha1
   kind: StoragePool
   name: pool1
   volume:
     name: vm-disks
   EOF
   
   The volume.name field names the volume the pool uses.
   The pool’s name can be up to 63 characters long and must start with a letter or digit. It can contain only ASCII letters, digits, hyphens, and underscores.
2. Apply the documents to the host:
   talosctl patch machineconfig --nodes <host-ip> --patch storage-pool.yaml
   
3. Check that the pool is ready:
   talosctl get storagepoolstatuses --nodes <host-ip>
   
   Talos reports each pool’s state in a StoragePoolStatus resource, with the following columns:
   • PHASE is ready once the pool is defined and active in libvirt.
   • TARGET is the pool’s directory on the host.
   • ERROR explains why a pool is not ready.
   • VOLUME is the backing volume’s ID, which Talos derives from its name. For example, a UserVolumeConfig named vm-disks has the ID u-vm-disks.

​

Change a storage pool’s volume

To point a pool at a different volume, change its volume.name and apply the change to the host. Talos then uses a directory on the new volume for the pool. Disk files in the old directory are not moved. A virtual machine disk in the pool gets a new, empty file on the new volume, and its data stays on the old volume. The change waits until no running virtual machine uses the pool. Until then, the pool’s PHASE is notReady, and its ERROR says that the pool is held. The following steps point pool1 at a new directory volume named vm-disks-2.

1. Run the following command to create storage-pool-new-volume.yaml, which declares the new volume and points pool1 at it:
   cat <<'EOF' > storage-pool-new-volume.yaml
   apiVersion: v1alpha1
   kind: UserVolumeConfig
   name: vm-disks-2
   volumeType: directory
   ---
   apiVersion: v1alpha1
   kind: StoragePool
   name: pool1
   volume:
     name: vm-disks-2
   EOF
   
2. Apply the documents to the host:
   talosctl patch machineconfig --nodes <host-ip> --patch storage-pool-new-volume.yaml
   
3. Check that the pool uses the new volume:
   talosctl get storagepoolstatuses --nodes <host-ip>
   
   The VOLUME column shows u-vm-disks-2, and PHASE shows ready once the pool is active on the new volume.

​

Remove a storage pool

Removing a pool stops it and removes it from libvirt. The pool’s files and its volume are not deleted, so its data stays on the volume. A pool cannot be removed while a virtual machine disk uses it. The patch that removes the pool must also remove those virtual machines, or change their disks to use a different pool. The following steps remove the pool1 storage pool.

1. Run the following command to create storage-pool-delete.yaml, a patch that deletes the pool1 document:
   cat <<'EOF' > storage-pool-delete.yaml
   apiVersion: v1alpha1
   kind: StoragePool
   name: pool1
   $patch: delete
   EOF
   
2. Apply it to the host:
   talosctl patch machineconfig --nodes <host-ip> --patch storage-pool-delete.yaml
   
3. Check that pool1 no longer appears in the output:
   talosctl get storagepoolstatuses --nodes <host-ip>
   

​

Next steps

To add a writable disk in a storage pool to a virtual machine, see Disks. To store the images that virtual machines boot from, see Upload and manage images.