This is unreleased documentation for SUSE® Virtualization v1.9 (Dev).

CSI Driver LVM

The harvester-csi-driver-lvm add-on is generally available (GA) starting with SUSE Virtualization v1.9.1. Volumes created with pre-GA versions are incompatible with the GA driver and are not supported.

The add-on is classified as experimental in SUSE Virtualization v1.9.0. For information about feature maturity, see Feature Labels.

This add-on is not included in the SUSE Virtualization ISO, but you can download the manifest (harvester-csi-driver-lvm-addon.yaml) from the Releases page. Manifest source files are located in the addons/standalone directory of the repository.

SUSE Virtualization allows you to use local storage on the host to create persistent volumes for your workloads with better performance and latency. This functionality is made possible by LVM, which provides logical volume management facilities on Linux.

The harvester-csi-driver-lvm add-on is a CSI driver that supports local path provisioning through LVM.

Supported Configuration

The driver provisions node-local LVM volumes. The volumes and the workloads that use them must be on the same node.

  • Use the ReadWriteOnce access mode. Multi-node ReadWriteMany (RWX) access is not supported. Pre-GA versions accepted RWX volumes, but those volumes did not provide true multi-node RWX semantics.

  • Use the dm-thin volume type. This is the only volume type included in the GA support scope.

  • Virtual machine live migration is not supported for VMs that use LVM volumes.

The striped volume type is deprecated and outside the GA support scope. Striped volumes do not provide the storage-efficient snapshot, clone, and restore behavior required by the supported CSI workflow. These operations require full data copies, which increase capacity and I/O requirements and can cause longer operations, retries, and timeouts.

Upgrading from a Pre-GA Release

Before upgrading the add-on to the GA version provided in Harvester v1.9.1 or later, back up all critical data and delete every LVM volume created with a pre-GA driver release. Pre-GA volumes are incompatible with the GA driver and cannot be recovered after upgrading.

Installing and enabling the add-on

If you are using the SUSE Virtualization kubeconfig file, you can install the add-on by performing the following steps:

  1. Run the following command:

    kubectl apply -f https://raw.githubusercontent.com/harvester/harvester/v1.9/addons/standalone/harvester-csi-driver-lvm/addon.yaml

  2. On the SUSE Virtualization UI, go to Advanced → Add-ons.

  3. Select harvester-csi-driver-lvm, and then select ⋮ → Enable.

Creating a volume group for LVM

A volume group combines physical volumes to create a single storage structure that can be divided into logical volumes.

SUSE Virtualization currently does not allow you to modify the volume group composition (add or remove disks) after you create a logical volume. This issue will be addressed in a future release.

When the driver provisions the first dm-thin volume in a volume group, it automatically creates <volume-group>-thinpool if that pool does not already exist. The driver applies the following creation policy:

  • Data capacity: 90% of currently free volume group extents for thin-pool data

  • Chunk size: 512 KiB

  • Active metadata: 16 GiB

  • Metadata repair spare: An enabled LVM repair spare approximately equal in size to the active metadata (~16 GiB)

The driver reserves approximately 32 GiB of total volume group capacity for active metadata and the repair spare. The repair spare provides redundancy for recovery operations and does not increase live metadata capacity. Ensure the volume group has sufficient free capacity to satisfy the data pool, active metadata, and repair spare allocations. Thin-pool creation fails if available space is insufficient.

The 16 GiB metadata allocation reduces the risk of metadata exhaustion but does not eliminate it.

If <volume-group>-thinpool already exists, the driver uses the pool as-is without modifying its geometry. Reusing an existing thin pool does not provide backward compatibility for volumes provisioned by pre-GA driver versions.

  1. Verify that the harvester-csi-driver-lvm add-on is installed.

  2. On the SUSE Virtualization UI, go to the Hosts screen.

  3. Select the target host, and then select ⋮ → Edit Config.

  4. On the Storage tab, add disks for the volume group.

    add disk to vg 01

    Configure the following settings for each selected disk:

    • Provisioner: Select LVM.

      add disk to vg 02

    • Volume Group: Select an existing volume group or specify a name for a new volume group.

      add disk to vg 03

      For more information about adding disks, see Multi-Disk Management.

  5. Click Save.

  6. On the host details screen, verify that the disks were added and the correct provisioner was set.

    add disk to vg 04

Creating a StorageClass for LVM

Use only the dm-thin volume type. The striped volume type is deprecated and excluded from the GA support scope.

  1. On the SUSE Virtualization UI, go to the Storage screen.

  2. Create a new StorageClass and select LVM in the Provisioner list.

    create lvm sc 01

  3. On the Parameters tab, configure the following settings:

    • Node: Select the target node for the intended workloads.

      create lvm sc 02

    • Volume Group Name: Select the volume group that you created.

      create lvm sc 03

    • Volume Group Type: Select dm-thin.

    • Volume Mode / Access Modes: On the CDI Settings tab, verify that the volume mode is Block and the access mode is ReadWriteOnce. For more information, see Containerized Data Importer (CDI) Settings.

  4. Click Save.

  5. On the Storage screen, verify that the StorageClass was created and the correct provisioner was set.

    create lvm sc 05

For more information, see StorageClass.

Creating a volume with LVM

  1. On the SUSE Virtualization UI, go to the Volumes screen.

  2. Create a new volume using the dm-thin LVM StorageClass that you created.

    create lvm volume 01

    The status Not Ready is normal because SUSE Virtualization creates the LVM volume only when the first workload is created.

  3. On the Virtual Machines screen, select the target virtual machine, and then select ⋮ → Add Volume.

    Because the LVM volume is a local volume, you must ensure that the target node of the LVM StorageClass is the node on which the virtual machine is scheduled.

  4. Specify the volume that you want to attach.

    attach lvm volume 01

  5. On the Volumes screen, verify that the state is In-use.

    attach lvm volume 02

You can also create a new virtual machine with the volume of the LVM StorageClass that you created. This virtual machine will be scheduled on the target node with local storage for the volume.

create vm with lvm volume 01
create vm with lvm volume 02

Creating snapshots for an LVM Volume

  1. On the SUSE Virtualization UI, go to the Settings screen.

  2. In the csi-driver-config section, select ⋮ → Edit Setting.

    update csi driver config 01

  3. Add an entry with the following settings:

    • Provisioner: Select lvm.driver.harvesterhci.io.

    • Volume Snapshot Class Name: Select lvm-snapshot.

  4. On the Virtual Machines screen, select the target virtual machine, and then select ⋮ → Take Virtual Machine Snapshot.

    Example:

    VM Snapshot with LVM Volume-1

  5. On the Virtual Machine Snapshots screen, verify that snapshot is ready to use.

    VM Snapshot with LVM Volume-2

Monitoring and Workload Planning

Monitor each thin pool directly on the node hosting its volume group. Run the following command to display data and metadata usage, read-only status, and health attributes:

sudo lvs -a <volume-group> \
  -o lv_name,lv_attr,data_percent,metadata_percent

Monitoring Metrics and Volume Attributes

The command’s output includes the following key fields:

  • Data% (-o data_percent): Percentage of data LV space currently used by thin volumes.

  • Meta% (-o metadata_percent): Percentage of metadata LV space currently used by the dm_thin_pool kernel module.

  • lv_attr: 10-character status string. For thin pools, inspect the following bit positions:

    • Second character (write permissions):

      • w: The logical volume is writable.

      • r: The logical volume is read-only.

    • Ninth character (thin-pool health):

      • F: The thin pool has failed.

      • D: The thin pool has exhausted its available data space.

      • M: The thin-pool metadata is in read-only mode.

Monitor Data% and Meta%, and take corrective action before either value reaches 100%. Exhausting thin-pool data or metadata can stall or fail I/O operations and block volume and snapshot creation. These behaviors are inherent to Linux device-mapper thin provisioning. For more information, see the LVM thin provisioning man page.

Workload Planning and Concurrency

Avoid overwhelming LVM storage with concurrent I/O-intensive workloads or simultaneous volume lifecycle operations (such as provisioning, cloning, snapshotting, and restoring). High resource contention increases latency and can cause application timeouts.

Optimal concurrency depends on your underlying storage hardware and workload I/O profiles. Validate your target concurrency levels through representative benchmark testing before deploying to production.

Supported LVM Volume Features

  • Volume resizing

  • Volume cloning

  • Snapshot creation

Backup creation is currently not supported. This limitation will be addressed in a future release.