Simplifying Persistent Storage in Harvester: Leveraging Longhorn‑Backed StorageClass

Why a Longhorn‑Backed StorageClass Matters

In a Kubernetes‑based hyperconverged platform like Harvester, persistent storage is a moving target. You need block‑level volumes that can be created on‑demand, replicated for high availability, and snapshotted for backups—all without pulling in a separate CSI plugin. Harvester’s built‑in support for a Longhorn‑backed StorageClass fills that niche. It lets you request dynamic volumes that are automatically distributed across cluster nodes, replicated by Longhorn’s consensus engine, and exposed to both VMs and containers with minimal configuration.

What the Feature Actually Does

• Dynamic provisioning – When a PersistentVolumeClaim (PVC) references the StorageClass, Harvester’s CSI driver hands the request to Longhorn, which creates a new block volume.
• Replication & snapshots – Longhorn automatically creates replicas on separate nodes and exposes CLI/API calls for snapshots and backups.
• Scheduling integration – The StorageClass can specify volumeBindingMode: WaitForFirstConsumer, letting Harvester’s scheduler pick the best node based on CPU/memory and storage locality.
• Zero external dependencies – No need to install a third‑party CSI plugin; the Longhorn driver is bundled with Harvester.

Step‑by‑Step: Creating a Longhorn‑Backed StorageClass

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: longhorn-harvester
provisioner: harvester.longhorn.io
parameters:
  replicaCount: "3"
  staleReplicaTimeout: "30"
volumeBindingMode: WaitForFirstConsumer
reclaimPolicy: Delete

Save the YAML to longhorn-sc.yaml and apply it:

# Run as a cluster admin
kubectl apply -f longhorn-sc.yaml

Verify the StorageClass exists:

kubectl get storageclass longhorn-harvester -o yaml

Key Parameters Explained

• replicaCount – Number of Longhorn replicas to maintain. Three replicas give 2‑node failover protection.
• staleReplicaTimeout – Time in minutes before a stale replica is considered dead.
• volumeBindingMode – WaitForFirstConsumer defers binding until a pod is scheduled, enabling node‑aware placement.

Using the StorageClass: A Practical PVC Example

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: myapp-pvc
spec:
  accessModes:
  - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi
  storageClassName: longhorn-harvester

Apply the PVC and check its status:

# Apply the PVC
kubectl apply -f myapp-pvc.yaml

# Wait until it becomes Bound
kubectl get pvc myapp-pvc -w

When the PVC is bound, Longhorn will have created a volume. To confirm:

# Describe the PVC
kubectl describe pvc myapp-pvc

# Look for the "VolumeName" field – it should reference a Longhorn volume
# Then use the Longhorn CLI through the Harvester node to inspect
kubectl exec -it -n harvester-system $(kubectl get pods -n harvester-system -l app=longhorn-manager -o jsonpath="{.items[0].metadata.name}") -- longhorn-manager get volume $(kubectl get pvc myapp-pvc -o jsonpath="{.spec.volumeName}")

Finally, run a simple I/O test to gauge performance:

# On a pod that mounts the PVC
kubectl run -i --tty fio-test --image=alpine --restart=Never --command sh
apk add --no-cache fio
cat > /tmp/fio_job.fio <<EOF
[global]
ioengine=sync
direct=1
size=1G
runtime=10
ramp_time=5
group_reporting

[write]
filename=/mnt/data
bs=4k
rw=write
EOF

# Mount the PVC to /mnt/data inside the pod and run fio
# (This is a simplified example – adjust paths as needed)

Trade‑offs & Practical Limitations

• Network latency – Replication traffic flows over the cluster network. In high‑latency environments, a replicaCount of 3 can noticeably reduce write performance.
• Storage overhead – Each replica consumes storage on a separate node. For a 10 Gi volume with 3 replicas, the cluster must have at least 30 Gi of free space distributed across nodes.
• RBAC exposure – The Harvester UI shows Longhorn credentials. Enforce strict role‑based access to avoid accidental data exposure.
• Legacy workloads – Old PVCs that reference other StorageClasses will not automatically migrate. Manual migration may be required.
• Snapshot quotas – Longhorn allows setting a snapshot quota per volume. Exceeding it can trigger automatic deletion of old snapshots.

Actionable Checklist for Adoption

1. Deploy or upgrade to Harvester v0.10+ (Longhorn integration is bundled).
2. Create the longhorn-harvester StorageClass with desired replica count.
3. Update existing PVCs to reference the new StorageClass, or create new ones for new workloads.
4. Enable volumeBindingMode: WaitForFirstConsumer for node‑aware placement.
5. Configure snapshot quotas and retention policies via the Harvester UI or longhorn-manager CLI.
6. Monitor replica health: kubectl get pods -n longhorn-system and longhorn-manager get volume output.
7. Set up alerts for replication lag or failed snapshots using Prometheus metrics exposed by Longhorn.

By following these steps, you can harness the full power of Longhorn’s replication and snapshotting while keeping the storage stack lightweight and tightly integrated with Harvester’s scheduler.