27 SUSE Storage V2 Data Engine #

Before enabling the V2 Data Engine, review the upstream V2 requirements. In particular, every node that can host a V2 replica requires:

Longhorn recommends using only one data engine after migration is complete. Running both engines creates separate instance managers and therefore consumes additional CPU and memory.

Prepare the required block devices before provisioning application volumes. Register each device as a block disk on its Longhorn node by using the SUSE Storage UI, or by updating the corresponding nodes.longhorn.io resource.

For a new cluster that has no V1 volumes, use the following Helm values:

defaultSettings:
  v1DataEngine: false
  v2DataEngine: true
persistence:
  dataEngine: v2

For an existing cluster with V1 volumes, keep both engines enabled during the migration:

defaultSettings:
  v1DataEngine: true
  v2DataEngine: true
persistence:
  dataEngine: v2

Apply the values with your normal Helm deployment or upgrade workflow. For example:

helm upgrade --install longhorn oci://dp.apps.rancher.io/charts/suse-storage \
  --version 1.12.1 \
  --namespace longhorn-system \
  --create-namespace \
  --reuse-values \
  --values suse-storage-v2-values.yaml

On an existing installation, confirm that the running Longhorn setting was enabled. If it remains disabled after the Helm upgrade, enable it explicitly:

kubectl -n longhorn-system patch settings.longhorn.io v2-data-engine \
  --type merge --patch '{"value":"true"}'

Caution

Do not disable the V1 Data Engine while any V1 volumes remain in the cluster. When upgrading an existing release, also confirm that --reuse-values does not preserve an older persistence.dataEngine value of v1.

Create a dedicated V2 StorageClass rather than changing an existing StorageClass in place:

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: longhorn-v2
provisioner: driver.longhorn.io
allowVolumeExpansion: true
reclaimPolicy: Delete
volumeBindingMode: Immediate
parameters:
  dataEngine: "v2"
  numberOfReplicas: "3"
  staleReplicaTimeout: "2880"
  fsType: "ext4"

To make V2 the default for PVCs that do not specify storageClassName, move the default annotation to the new StorageClass:

kubectl annotate storageclass longhorn \
  storageclass.kubernetes.io/is-default-class="false" --overwrite

kubectl annotate storageclass longhorn-v2 \
  storageclass.kubernetes.io/is-default-class="true" --overwrite

This change affects only newly provisioned volumes. It does not change the data engine of existing volumes.

Verify the settings, StorageClass, disks, and volumes:

kubectl -n longhorn-system get settings.longhorn.io \
  v1-data-engine v2-data-engine

kubectl get storageclass longhorn-v2 \
  -o jsonpath='dataEngine={.parameters.dataEngine}{"\n"}'

kubectl -n longhorn-system get nodes.longhorn.io

kubectl -n longhorn-system get volumes.longhorn.io \
  -o custom-columns='NAME:.metadata.name,ENGINE:.spec.dataEngine,STATE:.status.state,ROBUSTNESS:.status.robustness'

SUSE Storage 1.12.1 does not support converting an existing volume from V1 to V2 in place. Plan a maintenance window and migrate each workload to a new V2 volume.

For a filesystem volume that is not managed by a database or another application requiring a consistency-aware migration, a single maintenance pod can mount the V1 source read-only and the V2 destination read/write:

apiVersion: batch/v1
kind: Job
metadata:
  name: copy-v1-to-v2
  namespace: <application-namespace>
spec:
  backoffLimit: 3
  template:
    spec:
      restartPolicy: Never
      containers:
        - name: copy
          image: registry.suse.com/bci/bci-micro:latest
          command:
            - /bin/bash
            - -c
            - |
              set -euo pipefail
              cp -a /source/. /destination/
              sync
          volumeMounts:
            - name: source
              mountPath: /source
              readOnly: true
            - name: destination
              mountPath: /destination
      volumes:
        - name: source
          persistentVolumeClaim:
            claimName: <v1-pvc-name>
        - name: destination
          persistentVolumeClaim:
            claimName: <v2-pvc-name>

Warning

The copy Job is only a generic filesystem example. Use application-native backup and restore or replication for databases, raw block volumes, and applications with their own consistency requirements. Verify ownership, permissions, extended attributes, and application data before deleting the source PVC.

After every workload has been migrated, confirm that no V1 volumes remain:

kubectl -n longhorn-system get volumes.longhorn.io \
  -o custom-columns='NAME:.metadata.name,ENGINE:.spec.dataEngine,STATE:.status.state'

You can then disable the V1 Data Engine in the Helm values and upgrade the release:

defaultSettings:
  v1DataEngine: false
  v2DataEngine: true
persistence:
  dataEngine: v2

If the running setting remains enabled after the Helm upgrade, disable it explicitly:

kubectl -n longhorn-system patch settings.longhorn.io v1-data-engine \
  --type merge --patch '{"value":"false"}'

Run the volume inventory command again and confirm that no V1 volumes were overlooked before removing any V1-specific node storage.

Before moving a workload to V2, review the V1 and V2 feature comparison. The following limitations are especially relevant to SUSE Storage 1.12.1: