> ## Documentation Index > Fetch the complete documentation index at: https://docs.hyko.ai/llms.txt > Use this file to discover all available pages before exploring further. # Longhorn CSI 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:** ```bash theme={null} 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. ```bash theme={null} # 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:** ```bash theme={null} 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:** ```bash theme={null} 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! 🎉**