This is unreleased documentation for SUSE® Storage 1.12 (Dev).

Volume Expansion

Volumes are expanded in two stages. First, SUSE Storage resizes the block device, then it expands the file system.

SUSE Storage supports online expansion. Most of the time SUSE Storage can directly expand an attached volumes without limitations, no matter if the volume is being R/W or rebuilding.

If the volume was not expanded though the CSI interface (for example, for Kubernetes older than v1.16), the capacity of the corresponding PVC and PV do not change.

Prerequisites

For offline expansion, the SUSE Storage version must be v0.8.0 or later.
For online expansion (V1 Data Engine), the Longhorn version must be v1.4.0 or higher.
For online expansion (V2 Data Engine), the Longhorn version must be v1.10.0 or higher, and the volume must use the NVMe (NVMf) or Block Device front-end.

The UBLK front-end is not supported for online expansion as of v1.10.0

Expand a Longhorn volume

During the expansion process, SUSE Storage automatically resizes all replicas to match the user-requested size. There are two ways to expand a Longhorn volume: with a PersistentVolumeClaim (PVC) and with the SUSE Storage UI.

Via PVC

This method is applied only if:

The PVC is dynamically provisioned by the Kubernetes with Longhorn StorageClass.
The field allowVolumeExpansion should be true in the related StorageClass.

This method is recommended if it is applicable, because the PVC and PV is updated automatically and everything is kept consistent after expansion.

V1 Data Engine

Find the corresponding PVC for Longhorn volume, then modify the requested spec.resources.requests.storage of the PVC:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  annotations:
    kubectl.kubernetes.io/last-applied-configuration: |
      {"apiVersion":"v1","kind":"PersistentVolumeClaim","metadata":{"annotations":{},"name":"longhorn-simple-pvc","namespace":"default"},"spec":{"accessModes":["ReadWriteOnce"],"resources":{"requests":{"storage":"1Gi"}},"storageClassName":"longhorn"}}
    pv.kubernetes.io/bind-completed: "yes"
    pv.kubernetes.io/bound-by-controller: "yes"
    volume.beta.kubernetes.io/storage-provisioner: driver.longhorn.io
  creationTimestamp: "2019-12-21T01:36:16Z"
  finalizers:
  - kubernetes.io/pvc-protection
  name: longhorn-simple-pvc
  namespace: default
  resourceVersion: "162431"
  selfLink: /api/v1/namespaces/default/persistentvolumeclaims/longhorn-simple-pvc
  uid: 0467ae73-22a5-4eba-803e-464cc0b9d975
spec:
  accessModes:
  - ReadWriteOnce
  resources:
    requests:
      storage: 1Gi
  storageClassName: longhorn
  volumeMode: Filesystem
  volumeName: pvc-0467ae73-22a5-4eba-803e-464cc0b9d975
status:
  accessModes:
  - ReadWriteOnce
  capacity:
    storage: 1Gi
  phase: Bound

V2 Data Engine

For the V2 Data Engine, ensure your StorageClass has allowVolumeExpansion: true and dataEngine: "v2":

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

To expand the volume, edit the corresponding PVC manifest to increase the storage request to a larger size, then apply the updated manifest:

resources:
  requests:
    storage: 3Gi

Via SUSE Storage UI

Usage: On the Volumes page of the SUSE Storage UI, click Expand Volume* in the operation menu for the volume, enter the new desired size, and confirm. The expansion begins automatically. (For V2 Data Engine volumes, verify that the front-end is set to Block Device or NVMf before expanding).

Filesystem expansion

SUSE Storage tries to expand the file system only if:

The expanded size should be greater than the current size.
There is a Linux file system in the Longhorn volume.
The file system used in the Longhorn volume is one of the following:
Ext4
xfs
The expanded size must be less than the maximum file size allowed by the file system (for example, 16TiB for ext4).
The Longhorn volume is using the block device front-end.

Corner cases

Handling Volume Revert

If a volume is reverted to a snapshot with smaller size, the front-end of the volume is still holding the expanded size. But the file system size is the same as that of the reverted snapshot. In this case, you need to handle the file system manually:

Attach the volume to a random node.

If the file system is ext4, the volume might need to be mounted and umounted once before resizing the file system manually. Otherwise, executing resize2fs might result in an error:

resize2fs: Superblock checksum does not match superblock while trying to open ......
Couldn't find valid filesystem superblock.

Follow the steps below to resize the file system:

mount /dev/longhorn/<volume name> <arbitrary mount directory>
umount /dev/longhorn/<volume name>
mount /dev/longhorn/<volume name> <arbitrary mount directory>
resize2fs /dev/longhorn/<volume name>
umount /dev/longhorn/<volume name>

If the file system is xfs, you can directly mount, then expand the file system.

mount /dev/longhorn/<volume name> <arbitrary mount directory>
xfs_growfs <the mount directory>
umount /dev/longhorn/<volume name>

Encrypted volume

SUSE Storage support for online expansion depends on Kubernetes.

Kubernetes natively supports authenticated CSI storage resizing starting in v1.29.
In Kubernetes v1.25 to v1.28, the feature gate CSINodeExpandSecret is required.

You can enable online expansion for encrypted volumes by specifying the following encryption parameters in the StorageClass:

csi.storage.k8s.io/node-expand-secret-name
csi.storage.k8s.io/node-expand-secret-namespace

If you cannot enable it but still prefer to do online expansion, you can:

Login the node host the encrypted volume is attached to.
Execute cryptsetup resize <volume name>. The passphrase this command requires is the field CRYPTO_KEY_VALUE of the corresponding secret.
Expand the file system.

RWX volume

Starting with v1.8.0, SUSE Storage supports fully automatic online expansion of the file system (NFS) for RWX volumes. This feature requires that the v1.8.0 versions of the following components are running:

Longhorn Manager
CSI plug-in
Share Manager (manages the NFS export)

During upgrades, the Share Manager pods (one for each RWX volume) are not upgraded automatically to avoid disruptions.

After growing the block device, the CSI layer sends a resize command to the Share Manager to grow the file system within the block device. With a down-rev share-manager, the command fails with an "unimplemented" error code and so no expansion happens. To obtain the right image before the expansion, force a restart of the pod. Identify the Share Manager pod of the RWX volume (typically named share-manager-<volume name>) and delete it.

kubectl -n longhorn-system delete pod <the share manager pod>

The pod is automatically recreated using the appropriate version, and the expansion is completed. Further expansions do not require any further intervention.

Offline

Perform the following steps to allow expansion of RWX volumes while offline.

Detach the RWX volume by scaling down the workload to replicas=0. Ensure that the volume is fully detached.
After the scale command returns, run the following command and verify that the state is detached.
```
kubectl -n longhorn-system get volume <volume-name>
```
Expand the block device using either the PVC or the SUSE Storage UI.
Scale up the workload.

The reattached volume has the expanded size. Furthermore, the Share Manager pod is recreated with the current version.

References

[FEATURE] V2 Supports Volume Expansion