Longhorn

https://longhorn.io/docs/1.12.1/
Admin
Longhorn is a lightweight, reliable, and powerful distributed block storage system for Kubernetes.
Tokens:253,426
Snippets:1,989
Trust Score:9.5
Update:4 weeks ago
Show doc for...
Tokens:
Raw
### Example output of V1 install preflight

Source: https://longhorn.io/docs/1.12.1/deploy/install

Example output from running the V1 install preflight command, showing the installation steps and completion message.

```text
INFO[2025-03-11T08:17:57+08:00] Initializing preflight installer
INFO[2025-03-11T08:17:57+08:00] Cleaning up preflight installer
INFO[2025-03-11T08:17:57+08:00] Running preflight installer
INFO[2025-03-11T08:17:57+08:00] Installing dependencies with package manager
INFO[2025-03-11T08:18:28+08:00] Installed dependencies with package manager
INFO[2025-03-11T08:18:28+08:00] Cleaning up preflight installer
INFO[2025-03-11T08:18:28+08:00] Completed preflight installer. Use 'longhornctl check preflight' to check the result.

```

--------------------------------

### Successful Longhorn Installation Pod List

Source: https://longhorn.io/docs/1.12.1/deploy/install/install-with-fleet

Example output of a successful Longhorn installation, showing all expected pods in Running status. Use this to verify the installation completed successfully.

```text
NAME                                                READY   STATUS    RESTARTS   AGE
longhorn-ui-b7c844b49-w25g5                         1/1     Running   0          2m41s
longhorn-manager-pzgsp                              1/1     Running   0          2m41s
longhorn-driver-deployer-6bd59c9f76-lqczw           1/1     Running   0          2m41s
longhorn-csi-plugin-mbwqz                           2/2     Running   0          100s
csi-snapshotter-588457fcdf-22bqp                    1/1     Running   0          100s
csi-snapshotter-588457fcdf-2wd6g                    1/1     Running   0          100s
csi-provisioner-869bdc4b79-mzrwf                    1/1     Running   0          101s
csi-provisioner-869bdc4b79-klgfm                    1/1     Running   0          101s
csi-resizer-6d8cf5f99f-fd2ck                        1/1     Running   0          101s
csi-provisioner-869bdc4b79-j46rx                    1/1     Running   0          101s
csi-snapshotter-588457fcdf-bvjdt                    1/1     Running   0          100s
csi-resizer-6d8cf5f99f-68cw7                        1/1     Running   0          101s
csi-attacher-7bf4b7f996-df8v6                       1/1     Running   0          101s
csi-attacher-7bf4b7f996-g9cwc                       1/1     Running   0          101s
csi-attacher-7bf4b7f996-8l9sw                       1/1     Running   0          101s
csi-resizer-6d8cf5f99f-smdjw                        1/1     Running   0          101s
instance-manager-b34d5db1fe1e2d52bcfb308be3166cfc   1/1     Running   0          114s
engine-image-ei-df38d2e5-cv6nc                      1/1     Running   0          114s
```

--------------------------------

### Install prerequisites for V2 Data Engine with --enable-spdk

Source: https://longhorn.io/docs/1.12.1/deploy/install

Installs additional V2 prerequisites using the install preflight command with --enable-spdk.

```bash
longhornctl --kubeconfig ~/.kube/config --image longhornio/longhorn-cli:v1.12.1 install preflight --enable-spdk

```

--------------------------------

### Show created resources with kubectl get

Source: https://longhorn.io/docs/1.12.1/deploy/install/install-with-helm-controller

Show the created resources after applying the HelmChart: the installation job, the pod that runs the Helm install, and the HelmChart resource itself. The pod shows Completed status, indicating the installation job finished successfully.

```bash
$ kubectl get jobs
NAME                            COMPLETIONS   DURATION   AGE
helm-install-longhorn-install   0/1           8s         8s

$ kubectl get pods
NAME                                  READY   STATUS      RESTARTS   AGE
helm-install-longhorn-install-lngm8   0/1     Completed   0          25s

$ kubectl get helmcharts
NAME               JOB                     CHART      TARGETNAMESPACE   VERSION   REPO                         HELMVERSION   BOOTSTRAP
longhorn-install   helm-install-longhorn   longhorn   longhorn-system   v1.12.1    https://charts.longhorn.io

```

--------------------------------

### Install cryptsetup on SUSE/OpenSUSE

Source: https://longhorn.io/docs/1.12.1/deploy/install

Use this command to install cryptsetup for LUKS2 disk encryption support on SUSE/OpenSUSE.

```bash
zypper install cryptsetup

```

--------------------------------

### Install NFSv4 client on SUSE/OpenSUSE

Source: https://longhorn.io/docs/1.12.1/deploy/install

Use this command to install the NFSv4 client utilities on SUSE/OpenSUSE.

```bash
zypper install nfs-client

```

--------------------------------

### Install prerequisites for V1 Data Engine

Source: https://longhorn.io/docs/1.12.1/deploy/install

Installs base prerequisites for the default V1 installation path using the longhornctl install preflight command.

```bash
longhornctl --kubeconfig ~/.kube/config --image longhornio/longhorn-cli:v1.12.1 install preflight

```

--------------------------------

### Install longhornctl binary

Source: https://longhorn.io/docs/1.12.1/advanced-resources/longhornctl/install-longhornctl

Installs the downloaded longhornctl binary to /usr/local/bin using sudo install.

```bash
sudo install longhornctl-linux-${ARCH} /usr/local/bin/longhornctl
```

--------------------------------

### Install device mapper on SUSE/OpenSUSE

Source: https://longhorn.io/docs/1.12.1/deploy/install

Use this command to install the device mapper userspace tool (device-mapper) on SUSE/OpenSUSE.

```bash
zypper install device-mapper

```

--------------------------------

### System Managed CSI Components Resource Limits JSON Example

Source: https://longhorn.io/docs/1.12.1/references/settings

Example JSON object for the 'System Managed CSI Components Resource Limits' setting. Keys are component names and values are Kubernetes ResourceRequirements with requests and limits. Only listed components are overridden; others use Longhorn defaults.

```json
{
  "csi-attacher": {
    "requests": {"cpu": "100m", "memory": "128Mi"},
    "limits": {"cpu": "200m", "memory": "256Mi"}
  },
  "csi-provisioner": {
    "requests": {"cpu": "100m", "memory": "128Mi"},
    "limits": {"cpu": "200m", "memory": "256Mi"}
  },
  "longhorn-csi-plugin": {
    "requests": {"cpu": "100m", "memory": "128Mi"},
    "limits": {"cpu": "200m", "memory": "256Mi"}
  },
  "node-driver-registrar": {
    "requests": {"cpu": "50m", "memory": "64Mi"},
    "limits": {"cpu": "100m", "memory": "128Mi"}
  }
}
```

--------------------------------

### Check Danger Zone setting application with kubectl get setting

Source: https://longhorn.io/docs/1.12.1/references/settings

Check whether a Danger Zone setting has been applied by inspecting the APPLIED field. The output shows the setting priority-class with value longhorn-critical and APPLIED true.

```bash
~# kubectl -n longhorn-system get setting priority-class
NAME             VALUE               APPLIED   AGE
priority-class   longhorn-critical   true      3h26m

```

--------------------------------

### Example output: IOMMU enabled

Source: https://longhorn.io/docs/1.12.1/advanced-resources/v2-data-engine/interrupt-mode

Example output when IOMMU is enabled, showing device paths under the iommu_groups directories.

```text
/sys/kernel/iommu_groups/0/devices/0000:e6:0b.1
/sys/kernel/iommu_groups/1/devices/0000:34:0a.6
/sys/kernel/iommu_groups/2/devices/0000:a0:00.0
```

--------------------------------

### Install open-iscsi on Debian and Ubuntu

Source: https://longhorn.io/docs/1.12.1/deploy/install

Use this command to install open-iscsi on Debian and Ubuntu systems. The iscsid service is typically started automatically after installation.

```bash
apt-get install open-iscsi

```

--------------------------------

### Install Longhorn with kubectl apply

Source: https://longhorn.io/docs/1.12.1/deploy/install/install-with-kubectl

Applies the Longhorn v1.12.1 manifest to install Longhorn on a Kubernetes cluster. Run this command first to start the installation.

```bash
kubectl apply -f https://raw.githubusercontent.com/longhorn/longhorn/v1.12.1/deploy/longhorn.yaml

```

--------------------------------

### Set up SMB/CIFS Backupstore

Source: https://longhorn.io/docs/1.12.1/snapshots-and-backups/backup-and-restore/set-backup-target

Create a credential secret for SMB/CIFS backupstore and deploy it. The script generates a secret YAML with base64-encoded credentials and applies it. Then set environment variables, generate a Kustomize overlay, and deploy the credentials and service.

```bash
#!/bin/bash

USERNAME=${Username of SMB/CIFS Server}
PASSWORD=${Password of SMB/CIFS Server}

CIFS_USERNAME=`echo -n ${USERNAME} | base64`
CIFS_PASSWORD=`echo -n ${PASSWORD} | base64`

cat <<EOF >>cifs_secret.yml
apiVersion: v1
kind: Secret
metadata:
  name: cifs-secret
  namespace: longhorn-system
type: Opaque
data:
  CIFS_USERNAME: ${CIFS_USERNAME}
  CIFS_PASSWORD: ${CIFS_PASSWORD}
EOF

kubectl apply -f cifs_secret.yml

```

```bash
export CIFS_USERNAME="example-cifs-username"
export CIFS_PASSWORD="example-cifs-password"

```

```bash
./scripts/generate-backupstore-credentials.sh cifs

```

```bash
kubectl apply -k deploy/backupstores/overlays/generated-credentials/cifs

```

--------------------------------

### Expected pod list after Longhorn installation

Source: https://longhorn.io/docs/1.12.1/deploy/install/install-with-helm

Expected output of `kubectl -n longhorn-system get pod` after a successful Longhorn installation, showing all pods in Running state.

```text
NAME                                                READY   STATUS    RESTARTS   AGE
longhorn-ui-b7c844b49-w25g5                         1/1     Running   0          2m41s
longhorn-manager-pzgsp                              1/1     Running   0          2m41s
longhorn-driver-deployer-6bd59c9f76-lqczw           1/1     Running   0          2m41s
longhorn-csi-plugin-mbwqz                           2/2     Running   0          100s
csi-snapshotter-588457fcdf-22bqp                    1/1     Running   0          100s
csi-snapshotter-588457fcdf-2wd6g                    1/1     Running   0          100s
csi-provisioner-869bdc4b79-mzrwf                    1/1     Running   0          101s
csi-provisioner-869bdc4b79-klgfm                    1/1     Running   0          101s
csi-resizer-6d8cf5f99f-fd2ck                        1/1     Running   0          101s
csi-provisioner-869bdc4b79-j46rx                    1/1     Running   0          101s
csi-snapshotter-588457fcdf-bvjdt                    1/1     Running   0          100s
csi-resizer-6d8cf5f99f-68cw7                        1/1     Running   0          101s
csi-attacher-7bf4b7f996-df8v6                       1/1     Running   0          101s
csi-attacher-7bf4b7f996-g9cwc                       1/1     Running   0          101s
csi-attacher-7bf4b7f996-8l9sw                       1/1     Running   0          101s
csi-resizer-6d8cf5f99f-smdjw                        1/1     Running   0          101s
instance-manager-b34d5db1fe1e2d52bcfb308be3166cfc   1/1     Running   0          114s
engine-image-ei-df38d2e5-cv6nc                      1/1     Running   0          114s

```

--------------------------------

### Docker command example with actual values

Source: https://longhorn.io/docs/1.12.1/advanced-resources/data-recovery/export-from-replica

Example Docker command using the values from the previous steps: data path /var/lib/longhorn/replicas/pvc-06b4a8a8-b51d-42c6-a8cc-d8c8d6bc65bc-d890efb2, volume name pvc-06b4a8a8-b51d-42c6-a8cc-d8c8d6bc65bc, and size 1073741824.

```bash
docker run -v /dev:/host/dev -v /proc:/host/proc -v /var/lib/longhorn/replicas/pvc-06b4a8a8-b51d-42c6-a8cc-d8c8d6bc65bc-d890efb2:/volume --privileged longhornio/longhorn-engine:v1.12.1 launch-simple-longhorn pvc-06b4a8a8-b51d-42c6-a8cc-d8c8d6bc65bc 1073741824

```

--------------------------------

### Find kubelet root-dir with ps aux

Source: https://longhorn.io/docs/1.12.1/advanced-resources/os-distro-specific/csi-on-rke-and-coreos

Shows how to locate the kubelet root-dir by running ps aux and grepping for kubelet. The example output displays the --root-dir argument.

```bash
$ ps aux | grep kubelet
root      3755  4.4  2.9 744404 120020 ?       Ssl  00:45   0:02 kubelet --root-dir=/opt/rke/var/lib/kubelet --volume-plugin-dir=/var/lib/kubelet/volumeplugins
```

--------------------------------

### Install open-iscsi on SUSE and openSUSE

Source: https://longhorn.io/docs/1.12.1/deploy/install

Use these commands to install and start the open-iscsi service on SUSE and openSUSE systems. The iscsid daemon must be running for Longhorn to provide persistent volumes.

```bash
zypper install open-iscsi
systemctl enable iscsid
systemctl start iscsid

```

--------------------------------

### Install open-iscsi on RHEL, CentOS, and EKS

Source: https://longhorn.io/docs/1.12.1/deploy/install

Use these commands to install and configure open-iscsi on RHEL, CentOS, and EKS (with AmazonLinux2 image). The initiator name is set automatically, and the iscsid service is enabled and started.

```bash
yum --setopt=tsflags=noscripts install iscsi-initiator-utils
echo "InitiatorName=$(/sbin/iscsi-iname)" > /etc/iscsi/initiatorname.iscsi
systemctl enable iscsid
systemctl start iscsid

```

--------------------------------

### Create Argo CD namespace and install core components

Source: https://longhorn.io/docs/1.12.1/deploy/install/install-with-argocd

Run these commands to create the 'argocd' namespace and apply the Argo CD core installation manifest. Wait for the Argo CD components to be deployed before proceeding.

```bash
kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/core-install.yaml

```

--------------------------------

### Helm install with --set flag

Source: https://longhorn.io/docs/1.12.1/advanced-resources/deploy/customizing-default-settings

Use this command to install Longhorn with custom default settings by passing them directly via the --set flag. The example sets the taintToleration setting. Requires Helm 3.

```bash
helm install longhorn longhorn/longhorn \
  --namespace longhorn-system \
  --create-namespace \
  --set defaultSettings.taintToleration="key1=value1:NoSchedule; key2:NoExecute"

```

--------------------------------

### fleet.yaml: Specify Longhorn Helm chart

Source: https://longhorn.io/docs/1.12.1/deploy/install/install-with-fleet

Configures Fleet to install the Longhorn Helm chart from the Longhorn repository, with version v1.12.1 as an example.

```yaml
helm:
  repo: https://charts.longhorn.io
  chart: longhorn
  version: v1.12.1 # Replace with the Longhorn version you'd like to install or upgrade to
  releaseName: longhorn

```

--------------------------------

### Create Longhorn StorageClass with kubectl

Source: https://longhorn.io/docs/1.12.1/nodes-and-volumes/volumes/create-volumes

Run this command to create the Longhorn StorageClass from the official example file. This is the first step in the volume creation workflow.

```bash
kubectl create -f https://raw.githubusercontent.com/longhorn/longhorn/v1.12.1/examples/storageclass.yaml

```

--------------------------------

### Example: complete workflow with verification

Source: https://longhorn.io/docs/1.12.1/deploy/accessing-the-ui/longhorn-ingress-traefik

Shows the complete workflow from creating the auth secret to verifying the Ingress with curl, including expected output for unauthorized and authorized requests.

```bash
$ USER=foo; PASSWORD=bar; echo "${USER}:$(openssl passwd -stdin -apr1 <<< ${PASSWORD})" > auth
$ kubectl -n longhorn-system create secret generic basic-auth --from-file=auth
secret/basic-auth created

# (After applying middlewares and ingress manifests)

$ kubectl -n longhorn-system get ingress
NAME               CLASS     HOSTS   ADDRESS      PORTS   AGE
longhorn-ingress   traefik   * 10.0.2.15    80      15s

$ curl -I http://10.0.2.15/
HTTP/1.1 401 Unauthorized
Www-Authenticate: Basic realm="traefik"

$ curl -u foo:bar -I http://10.0.2.15/
HTTP/1.1 200 OK

```

--------------------------------

### Update and install a valid linux-modules-extra version (Ubuntu 22.04)

Source: https://longhorn.io/docs/1.12.1/troubleshoot/troubleshooting

These commands update the package list and install a specific version of the Linux kernel extra modules package that is known to be available. This is provided as a resolution for the previous error, using version 5.15.0-76-generic as an example.

```bash
apt update -y
apt install -y linux-modules-extra-5.15.0-76-generic
```

--------------------------------

### Load iscsi_tcp module

Source: https://longhorn.io/docs/1.12.1/deploy/install

Ensure the iscsi_tcp module is loaded before the iscsid service starts. This is generally done automatically with the package installation, but can be done manually with this command.

```bash
modprobe iscsi_tcp

```

--------------------------------

### Example output of V1 preflight check

Source: https://longhorn.io/docs/1.12.1/deploy/install

Example output from running the V1 preflight check, showing info and warnings for worker nodes.

```text
INFO[2024-01-01T00:00:01Z] Initializing preflight checker
INFO[2024-01-01T00:00:01Z] Cleaning up preflight checker
INFO[2024-01-01T00:00:01Z] Running preflight checker
INFO[2024-01-01T00:00:02Z] Retrieved preflight checker result:
worker1:
  info:
  - Service iscsid is running
  - NFS4 is supported
  - Package nfs-common is installed
  - Package open-iscsi is installed
  warn:
  - multipathd.service is running. Please refer to https://longhorn.io/kb/troubleshooting-volume-with-multipath/ for more information.
worker2:
  info:
  - Service iscsid is running
  - NFS4 is supported
  - Package nfs-common is not installed
  - Package open-iscsi is installed

```

--------------------------------

### Check prerequisites for V1 Data Engine

Source: https://longhorn.io/docs/1.12.1/deploy/install

Runs the base preflight check for the default V1 installation path.

```bash
./longhornctl check preflight

```
Tokens:
Raw