Longhorn 1.11.1

FractalOps pins the upstream Longhorn Helm chart 1.11.1. Investigation date: 2026-07-22. Architecture authority: ADR 0019.

Supported Path

Give each storage worker an exclusive local block device with ext4 or XFS and a stable mount path. Do not use a network LUN as a Longhorn disk.
Before Longhorn first observes a new node, apply node.longhorn.io/create-default-disk=config and a node.longhorn.io/default-disks-config JSON annotation. The JSON supplies the environment mount path, scheduling state, reserve, and portable tier tags.
Keep hostnames and hypervisor device identifiers in the environment provisioner, outside application and StorageClass manifests.
Use separate physical devices on separate nodes for replica failure domains.
Use fractalops-longhorn-cnpg-rwo for CloudNativePG PGDATA and WAL. It combines WaitForFirstConsumer, one Longhorn replica, and strict-local data locality; CNPG supplies database replication and required pod anti-affinity.
Run the native snapshot-cleanup job daily and filesystem-trim weekly. Neither grants permission to delete valid snapshots or retained volumes.

Example enrollment shape:

kubectl annotate node "$NODE" node.longhorn.io/default-disks-config='[{"name":"capacity","path":"/var/mnt/longhorn","allowScheduling":true,"storageReserved":107374182400,"tags":["durable","fast","workspace"]}]'
kubectl label node "$NODE" node.longhorn.io/create-default-disk=config

The three tags let the capacity disk receive every Assembly-owned local Longhorn class. Omit a tag only when that worker intentionally excludes the corresponding workload tier.

Traps

The annotation is bootstrap-only: Longhorn ignores it when the node already has disks or tags. Change an existing Longhorn Node through an explicit migration.
A replica count greater than one consumes real capacity for every replica. Native database or object-store replication can make an extra Longhorn replica wasteful.
Do not use an Immediate class with disabled locality for CNPG. The volume may land on another node, making base backup and normal database I/O cross the storage network.
Filesystem trim cannot reclaim blocks held by valid snapshots. Snapshot deletion is a separate owner-approved action.
Over-provisioning is a scheduling limit, not physical capacity. Add real disks before lowering a saturated cluster’s limit, then verify schedulable and actual bytes.
Longhorn V1 still requires open-iscsi on Kubernetes nodes for its frontend. That package requirement does not authorize an external iSCSI storage backend.
A tainted legacy node can retain replicas while its Longhorn manager is absent. For a bounded drain, temporarily tolerate that node taint on longhorn-manager, wait until every scheduled replica and backing image reaches zero, then restore the Assembly chart. Never delete the last healthy replica to bypass a stuck eviction.

First Capacity Enrollment Evidence

The first dedicated worker exposed 1,967,847,137,280 bytes to Longhorn with a 100 GiB reserve and durable, fast, and workspace tags. At the initial migration check it had 1,838,782,873,600 bytes available. Native replica evacuation increased placement on the capacity disk from 14 to 23 replicas without a degraded or faulted volume. No external iSCSI target was configured; the physical device was attached exclusively to the Kubernetes worker.

Verification

kubectl get nodes -L node.longhorn.io/create-default-disk
kubectl -n longhorn-system get nodes.longhorn.io -o wide
kubectl -n longhorn-system get recurringjobs.longhorn.io
kubectl -n longhorn-system get volumes.longhorn.io

Authoritative references: default disk and node configuration, multiple disks, storage class parameters, recurring jobs, filesystem trim, best practices, and CloudNativePG block storage guidance.