Enterprise Storage Integration (CSI)

SUSE Virtualization ships with SUSE Storage as the built-in storage system. However, SUSE Virtualization also supports provisioning root volumes and data volumes using external Container Storage Interface (CSI) drivers. This allows integration with existing enterprise SAN or NAS storage solutions.

1. Preventing Storage Conflicts

When presenting external storage block devices to SUSE Virtualization nodes, ensure that SUSE Virtualization and the built-in SUSE Storage engine do not attempt to claim or wipe them.

Harvester Disk Filtering (v1.8+): SUSE Virtualization v1.8 manages disk discovery and auto-provisioning via the harvester-node-disk-manager ConfigMap in the harvester-system namespace. You must explicitly exclude your enterprise storage devices, vendors, or mount paths in the filters.yaml section to prevent SUSE Virtualization from managing them.
Harvester Auto-Provisioning: Ensure your external storage device paths are never listed in the autoprovision.yaml section of the harvester-node-disk-manager ConfigMap. Any device selected for automatic provisioning will be completely erased. For configuration details, see Filter out and auto provision disks.
File System-Type Disks: SUSE Virtualization overrides the upstream SUSE Storage configuration and creates a default file system-type disk at /var/lib/harvester/defaultdisk. Do not mount external storage to this path.
Block-Type Disks: The V2 Data Engine requires raw block devices. If your external storage presents raw block devices (for example, NVMe or VirtIO) to the host, do not add these paths to the SUSE Storage UI or spec.disks configuration.
Longhorn Custom Provisioning: If you are manually configuring Longhorn defaults using the node.longhorn.io/create-default-disk: 'config' label alongside the node.longhorn.io/default-disks-config annotation, ensure this configuration does not target your external storage paths.

2. Host OS Preparation

Because SUSE Virtualization follows an immutable OS design, software packages or persistent paths required by enterprise CSI drivers must be configured explicitly in the cluster configuration file.

Configure custom paths with os.persistent_state_paths.
Install required host packages with os.after_install_chroot_commands.

Upgrading SUSE Virtualization causes OS changes made in the after-install-chroot stage to be lost. You must also configure after-upgrade-chroot to ensure package changes persist across cluster upgrades. Refer to Runtime persistent changes before upgrading.

For CSI drivers requiring Multipath I/O (multipathd), see Multipath Support for host execution and CloudInit CRD examples.

3. Installing the CSI Driver

Before installing an enterprise CSI driver, verify that it supports the required baseline capabilities detailed in Third-Party Storage Prerequisites (including online volume expansion, snapshot creation, cloning, and RWX volumes for Live Migration).

Obtain your cluster credentials as described in How can I access the kubeconfig file? and install the vendor’s CSI driver following their deployment instructions.

4. Harvester CSI Configuration

After installing the CSI driver and creating its corresponding VolumeSnapshotClass, you must map the provisioner to this snapshot class using SUSE Virtualization’s csi-driver-config setting. Without this mapping, VM and volume snapshots will fail.

Navigate to Advanced → Settings in the UI to update the csi-driver-config. For step-by-step instructions, see Configure the SUSE Virtualization cluster.

You only need to configure the Volume Snapshot Class Name. Leave the Backup VolumeSnapshot Class Name empty, as SUSE Virtualization’s native backup feature is strictly limited to SUSE Storage volumes.

5. StorageClass and CDI Configuration

SUSE Virtualization integrates with the Containerized Data Importer (CDI) to handle VM image management. If your Enterprise StorageClass provisioner is not included in CDI’s default capabilities list, you must annotate the StorageClass with cdi.harvesterhci.io/storageProfileVolumeModeAccessModes. Without this annotation, image deployments or Helm chart installations may fail.

Apply CDI annotations directly to the StorageClass. Crucially, the cdi.harvesterhci.io/storageProfileVolumeModeAccessModes annotation must match your CSI driver’s actual supported capabilities. For example, use Filesystem for NAS/NFS drivers, as they do not support block volumes.

For full attribute descriptions and configuration rules, see Containerized Data Importer (CDI) Settings.

The following example demonstrates a StorageClass annotated for a SAN-backed block-storage driver:

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: enterprise-csi
  annotations:
    cdi.harvesterhci.io/storageProfileCloneStrategy: snapshot
    # Ensure this matches the driver's capability (e.g., use "Filesystem" for NAS/NFS)
    cdi.harvesterhci.io/storageProfileVolumeModeAccessModes: '{"Block":["ReadWriteOnce"]}'
    cdi.harvesterhci.io/storageProfileVolumeSnapshotClass: enterprise-snapshot
    cdi.harvesterhci.io/filesystemOverhead: '0.05'
provisioner: csi.enterprise-vendor.com
reclaimPolicy: Delete
volumeBindingMode: WaitForFirstConsumer
allowVolumeExpansion: true

6. Validating the Integration

Before placing production workloads on external storage, validate your CSI driver’s compatibility using the storage-validator utility.

Download the executable from the Releases page.
Create a config.yml file pointing to your enterprise StorageClass and matching VolumeSnapshotClass.
Execute the validation test suite:
```
storage-validator -config ./config.yml
```

For a detailed breakdown of configuration options, test cases, and expected output examples, see Storage Validator.

7. Using the CSI Driver

Once configured and validated, external storage can be selected during standard VM operations:

Virtual Machine Creation: Select your enterprise StorageClass on the Volumes tab during Virtual Machine Creation. Ensure you select the Volume Mode supported by your CSI driver and StorageClass configuration (for example, Filesystem for NFS, whereas SAN-backed CSI drivers may support either Filesystem or Block depending on how they present the volume to Kubernetes).
Limitations: Review Third-Party Storage Limitations regarding VM backup restrictions (limited to SUSE Storage) and detached PVC prerequisites when exporting images.