Skip to main content
Longhorn is a free, open-source distributed block storage system for Kubernetes that keeps things lightweight while handling replication and persistence for your workloads.​​​​​​​​​​​​​​​​ If you’ve got a K8s cluster deployed on Latitude.sh and need reliable container storage, this guide will get you there.

​
Prerequisites

​
Step 1: Prepare your cluster

1

Check available disks

Run lsblk on each node to find available disks and partitions to dedicate to Longhorn.
2

Label nodes (Optional)

Label your nodes to control which ones will be used for Longhorn storage:
kubectl label nodes <node-name> longhorn=true

​
Step 2: Install Longhorn

Longhorn can be installed on a K8s cluster in several ways. In this guide, we’ll go with Helm.
1

Add Longhorn repository

Add the Longhorn Helm repository:
helm repo add longhorn https://charts.longhorn.io
helm repo update
2

Install Longhorn

Run this command to install Longhorn:
helm install longhorn longhorn/longhorn --namespace longhorn-system --create-namespace
3

Verify installation

Verify the installation:
kubectl -n longhorn-system get pod
All pods should be running without errors.

​
Step 3: Access the Longhorn UI

1

Check services

Run this command to check if the Longhorn services are up:
kubectl -n longhorn-system get svc
The output should be something like this:Longhorn frontend service
2

Set up port forwarding

Set up port forwarding to the frontend service:
kubectl port-forward services/longhorn-frontend 8080:http -n longhorn-system
3

Access dashboard

Navigate to http://localhost:8080 in your browser to access the Longhorn UI. You’ll be taken to this dashboard:Longhorn dashboard UI

​
Step 4: Configure storage

1

Check nodes

In the Longhorn UI, navigate to Node and check if your disks are detected automatically.Longhorn node page
2

Define disk usage limits

Define disk usage limits and scheduling. Make sure your nodes have enough space to handle the intended workload.

​
Step 5: Create a StorageClass

1

Create StorageClass manifest

Create a StorageClass manifest named longhorn-storageclass.yaml:
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: longhorn
provisioner: driver.longhorn.io
allowVolumeExpansion: true
reclaimPolicy: Delete
volumeBindingMode: Immediate
2

Apply StorageClass

Apply the StorageClass:
kubectl apply -f longhorn-storageclass.yaml
3

Set as default (Optional)

Set the StorageClass as default:
kubectl patch storageclass longhorn -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'

​
Step 6: Create a PersistentVolumeClaim (PVC)

1

Create PVC manifest

Create a PersistentVolumeClaim YAML file named longhorn-pvc.yaml:
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: longhorn-pvc
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: longhorn
  resources:
    requests:
      storage: 5Gi
2

Apply PVC

Apply the PVC:
kubectl apply -f longhorn-pvc.yaml
3

Verify PVC

Verify the PVC:
kubectl get pvc
Make sure the status shows Bound to confirm it worked.

​
Step 7: Use the PVC in a Pod

1

Create Pod manifest

Create a Pod that Uses the PVC, save this as longhorn-pod.yaml:
apiVersion: v1
kind: Pod
metadata:
  name: longhorn-test-pod
spec:
  containers:
    - name: longhorn-test
      image: nginx
      volumeMounts:
        - mountPath: "/usr/share/nginx/html"
          name: longhorn-storage
  volumes:
    - name: longhorn-storage
      persistentVolumeClaim:
        claimName: longhorn-pvc
2

Deploy Pod

Deploy the Pod:
kubectl apply -f longhorn-pod.yaml
3

Check Pod status

Check Pod status:
kubectl get pods
The Pod should be running without issues. You can check if the data persists by inspecting the mounted directory.

​
Troubleshooting

  • If Longhorn nodes show as unschedulable, check disk space and ensure no taints are blocking pods.
  • For performance tuning, you can adjust the number of replicas for each volume in the Longhorn UI under Settings > Default Settings.
  • If using firewalls, ensure ports 9500-9600 are open for communication between Longhorn components.

​
That’s it!

You’ve got Longhorn running and ready to handle your persistent storage needs.