UBLK Frontend Support for SUSE Storage (Longhorn) v2 Data Engine

Longhorn’s v2 data engine (SPDK-based) can expose volumes as Linux block devices using different frontends. By default, v2 volumes use NVMe-oF, but you can also choose the UBLK frontend, which exposes a v2 volume as a local block device using the Linux ublk driver plus SPDK’s ublk framework.

Prereqs (and a quick warning)

• Nodes must run Linux kernel v6.0+ (ublk support starts at 6.0).
• The kernel module ublk_drv must be loaded on nodes that will attach UBLK volumes:

  sudo modprobe ublk_drv
  

• Longhorn version >= v1.9.0

Why use UBLK?

In certain high-spec environments (fast SSDs + many CPU cores), UBLK can outperform NVMe-oF for v2 volumes. If you’re chasing maximum IOPS/throughput and you meet the kernel requirement, UBLK is worth evaluating.
See the reference Longhorn-Performance-Investigation for more testing data.

How to use it

Option 1: Longhorn UI

When creating a v2 volume in the Longhorn UI, select Frontend = UBLK.

Option 2: StorageClass

Create a StorageClass that pins dataEngine: v2 and frontend: ublk:

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

Then create your PVC using storageClassName: longhorn-v2-ublk. For example:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: my-ublk-frontend-pvc
  namespace: default
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: longhorn-v2-ublk
  resources:
    requests:
      storage: 10Gi

Tuning ublkNumberOfQueue and ublkQueueDepth

Two common performance knobs for the UBLK frontend are:

• ublkNumberOfQueue: number of UBLK queues
• ublkQueueDepth: queue depth per queue

Here’s a StorageClass example that sets both:

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: longhorn-v2-ublk-tuned
provisioner: driver.longhorn.io
allowVolumeExpansion: true
reclaimPolicy: Delete
volumeBindingMode: Immediate
parameters:
  dataEngine: "v2"
  frontend: "ublk"
  numberOfReplicas: "1"
  fsType: "ext4"
  staleReplicaTimeout: "2880"
  # UBLK tuning (example values)
  ublkNumberOfQueue: "2"
  ublkQueueDepth: "256"

Then create your PVC using storageClassName: longhorn-v2-ublk-tuned. For example:

```yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: my-ublk-frontend-pvc
  namespace: default
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: longhorn-v2-ublk-tuned
  resources:
    requests:
      storage: 10Gi

Wrap-up

UBLK frontend support provides Longhorn v2 data engine users with an additional way to unlock performance—especially on modern kernels and high-throughput nodes. With tunables like ublkNumberOfQueue and ublkQueueDepth, you can shape the frontend behavior to better match your workload.