Skip to main content
This guide walks you through installing Longhorn, a cloud-native distributed block storage system for Kubernetes, on your Talos cluster.

​
What is Longhorn?

Longhorn is a lightweight, reliable, and powerful distributed block storage system for Kubernetes. Created by Rancher Labs (now part of SUSE), it provides:
  • Persistent storage for your applications
  • Built-in backup and restore capabilities
  • Volume replication across nodes for high availability
  • Snapshots for point-in-time recovery
  • User-friendly web UI for management
  • Disaster recovery with cross-cluster replication
Unlike traditional storage solutions, Longhorn runs entirely in Kubernetes and is easy to install and manage.

​
Prerequisites

Before installing Longhorn, you need to:
  1. Have a running Talos Kubernetes cluster (see the deployment guide)
  2. Rebuild your Talos nodes with required system extensions
  3. Have kubectl configured to access your cluster
Longhorn requires specific system extensions to function properly on Talos. These extensions provide the necessary storage tools that aren’t included in Talos by default.

​
Required Extensions

You need two system extensions:
  1. siderolabs/iscsi-tools: Provides iSCSI (Internet Small Computer Systems Interface) support
    • iSCSI allows Longhorn to attach block storage volumes to pods
    • This is how Kubernetes mounts persistent volumes to containers
  2. siderolabs/util-linux-tools: Provides essential Linux utilities
    • Contains tools like nsenter, lsblk, and findmnt
    • Required for volume mounting and filesystem operations

​
Configure Namespace Security

Longhorn requires privileged access to manage storage at the system level. We need to configure the namespace with appropriate Pod Security Standards. What are Pod Security Standards? Kubernetes Pod Security Standards define three policies:
  • Privileged: Unrestricted policy (required for system-level operations)
  • Baseline: Minimally restrictive policy
  • Restricted: Heavily restricted policy (most secure)
Longhorn needs privileged access because it:
  • Manages block devices and filesystems
  • Mounts volumes to nodes
  • Performs low-level storage operations
  • Interacts directly with the kernel
Create the namespace with security labels: 
kubectl create namespace longhorn-system

kubectl label namespace longhorn-system \
  pod-security.kubernetes.io/enforce=privileged \
  pod-security.kubernetes.io/enforce-version=latest \
  pod-security.kubernetes.io/audit=privileged \
  pod-security.kubernetes.io/audit-version=latest \
  pod-security.kubernetes.io/warn=privileged \
  pod-security.kubernetes.io/warn-version=latest
What each label means:
  • enforce=privileged: Pods violating this policy will be rejected
  • audit=privileged: Policy violations are logged to the audit log
  • warn=privileged: Users receive warnings for policy violations
  • version=latest: Use the latest version of the policy standard

​
Add Longhorn Helm Repository

Longhorn is distributed via Helm charts, which are packages for Kubernetes applications. 
# Add the Longhorn Helm repository
helm repo add longhorn https://charts.longhorn.io

# Update your local Helm chart repository cache
helm repo update

# Verify the repository was added
helm search repo longhorn
Expected output: 
NAME                    CHART VERSION   APP VERSION     DESCRIPTION
longhorn/longhorn       1.9.0           v1.9.0          Longhorn is a distributed block storage system...

​
Install Longhorn

Now we’ll install Longhorn with configuration optimized for a 2-worker-node cluster. Install command: 
helm install longhorn longhorn/longhorn \
  --namespace longhorn-system \
  --version 1.9.0 \
  --set persistence.defaultClassReplicaCount=2 \
  --set defaultSettings.defaultReplicaCount=2
What these settings mean:

​
persistence.defaultClassReplicaCount=2

  • Sets the default number of replicas for the default StorageClass
  • Replication means each volume is copied to multiple nodes
  • With 2 replicas across 2 worker nodes:
    • Your data exists on both workers
    • If one worker fails, data remains accessible
    • Provides high availability for your volumes
  • Default is 3, but we only have 2 worker nodes

​
defaultSettings.defaultReplicaCount=2

  • Sets the global default for all Longhorn volumes
  • Ensures any volume created gets 2 replicas by default
  • Applies to all StorageClasses, not just the default one
Why replica count matters:
  • 1 replica: No redundancy—if that node fails, data is lost
  • 2 replicas: Can tolerate 1 node failure
  • 3 replicas: Can tolerate 2 node failures (requires 3+ nodes)
Installation process takes 2-5 minutes. Helm will:
  1. Create CustomResourceDefinitions (CRDs) for Longhorn objects
  2. Deploy the Longhorn manager (control plane)
  3. Deploy Longhorn engine (data plane)
  4. Create DaemonSets to run storage agents on each node
  5. Set up the Longhorn UI
  6. Create the default StorageClass

​
Step 5: Verify Installation

Check pod status: 
kubectl get pods -n longhorn-system
Expected output (wait until all pods show Running): 
NAME                                        READY   STATUS    RESTARTS   AGE
csi-attacher-...                            1/1     Running   0          2m
csi-provisioner-...                         1/1     Running   0          2m
csi-resizer-...                             1/1     Running   0          2m
csi-snapshotter-...                         1/1     Running   0          2m
engine-image-ei-...                         1/1     Running   0          2m
instance-manager-...                        1/1     Running   0          2m
longhorn-csi-plugin-...                     3/3     Running   0          2m
longhorn-driver-deployer-...                1/1     Running   0          3m
longhorn-manager-...                        1/1     Running   0          3m
longhorn-ui-...                             1/1     Running   0          3m
you can now use the storageClass longhorn in your pvcs and it will schedule 2 replicas per volume You now have production-ready persistent storage in your Kubernetes cluster! 🎉