Longhorn

https://longhorn.io/docs/1.10.0
Admin
Longhorn is a lightweight, reliable, and powerful distributed block storage system for Kubernetes,...
Tokens:64,690
Snippets:433
Trust Score:9.5
Update:1 year ago
Show doc for...
Tokens:
Raw
### Example Longhorn System Pods Status

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

This is an example output showing the expected status of Longhorn pods after a successful installation. All listed CSI, engine, instance manager, and Longhorn-specific pods should be in a 'Running' state.

```text
NAME                                                READY   STATUS    RESTARTS      AGE
csi-attacher-85c7684cfd-67kqc                       1/1     Running   0             29m
csi-attacher-85c7684cfd-jbddj                       1/1     Running   0             29m
csi-attacher-85c7684cfd-t85bw                       1/1     Running   0             29m
csi-provisioner-68cdb8b96-46d9q                     1/1     Running   0             29m
csi-provisioner-68cdb8b96-dgf5f                     1/1     Running   0             29m
csi-provisioner-68cdb8b96-mh8q7                     1/1     Running   0             29m
csi-resizer-86dd765b9-d27cs                         1/1     Running   0             29m
csi-resizer-86dd765b9-scqxm                         1/1     Running   0             29m
csi-resizer-86dd765b9-zpcv7                         1/1     Running   0             29m
csi-snapshotter-65b46b8749-dtvh2                    1/1     Running   0             29m
csi-snapshotter-65b46b8749-g67fn                    1/1     Running   0             29m
csi-snapshotter-65b46b8749-nfgzm                    1/1     Running   0             29m
engine-image-ei-221c9c21-gd5d6                      1/1     Running   0             29m
engine-image-ei-221c9c21-v6clp                      1/1     Running   0             29m
engine-image-ei-221c9c21-zzdrt                      1/1     Running   0             29m
instance-manager-77d11dda6091967f9b30011c9876341b   1/1     Running   0             29m
instance-manager-870c250b69a4fe01382ed46156d33f47   1/1     Running   0             29m
instance-manager-a4099c5ce28b423c3cc2667906f4b0b4   1/1     Running   0             29m
longhorn-csi-plugin-jfbh5                           3/3     Running   0             29m
longhorn-csi-plugin-w768w                           3/3     Running   0             29m
longhorn-csi-plugin-xcghm                           3/3     Running   0             29m
longhorn-driver-deployer-586bc86bf9-bkwk6           1/1     Running   0             30m
longhorn-manager-c4xtv                              1/1     Running   1 (30m ago)   30m
longhorn-manager-kgqts                              1/1     Running   0             30m
longhorn-manager-n8xdr                              1/1     Running   0             30m
longhorn-ui-69667f9678-2lvxn                        1/1     Running   0             30m
longhorn-ui-69667f9678-2xmc9                        1/1     Running   0             30m

```

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

### Longhorn CLI preflight check example

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

Demonstrates the usage of the `longhornctl check preflight` command, which verifies Kubernetes cluster environment readiness for Longhorn. The output shows example checks for services, packages, loaded modules, and warnings.

```shell
> longhornctl check preflight
INFO[2025-08-22T12:58:40+08:00] Initializing preflight checker               
INFO[2025-08-22T12:58:40+08:00] Cleaning up preflight checker                
INFO[2025-08-22T12:58:42+08:00] Running preflight checker                    
INFO[2025-08-22T12:58:49+08:00] Retrieved preflight checker result:
ip-10-0-1-132:
  info:
  - Service iscsid is running
  - NFS4 is supported
  - Package nfs-client is installed
  - Package open-iscsi is installed
  - Package cryptsetup is installed
  - Package device-mapper is installed
  - Module dm_crypt is loaded
  warn:
  - Kube DNS "coredns" is set with fewer than 2 replicas; consider increasing replica count for high availability
INFO[2025-08-22T12:58:49+08:00] Cleaning up preflight checker                
INFO[2025-08-22T12:58:50+08:00] Completed preflight checker

```

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

### Install Cryptsetup (SUSE/OpenSUSE)

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

Installs the `cryptsetup` utility on SUSE and OpenSUSE distributions using `zypper`. This is required for Longhorn's volume encryption functionality.

```shell
zypper install cryptsetup

```

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

### Install Cryptsetup (Debian/Ubuntu)

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

Installs the `cryptsetup` utility on Debian and Ubuntu systems using `apt-get`. This tool is essential for Longhorn's volume encryption feature, which utilizes LUKS2.

```shell
apt-get install cryptsetup

```

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

### Install Preflight Dependencies with Kubeconfig and Image

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

Installs preflight dependencies for Longhorn using the longhornctl command, specifying the kubeconfig path and the Longhorn CLI Docker image. This method allows for more control over the installation process.

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

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

### Install Preflight Dependencies with Longhorn CLI

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

Uses the longhornctl command with the 'install preflight' sub-command to set up and install the necessary dependencies for Longhorn. This command may require a reboot on certain immutable Linux distributions.

```bash
./longhornctl install preflight
```

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

### Install Device Mapper (Debian/Ubuntu)

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

Installs the `dmsetup` tool on Debian and Ubuntu systems using `apt-get`. This utility is part of the device mapper framework, crucial for Longhorn's storage operations and encryption.

```shell
apt-get install dmsetup

```

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

### Download and Run Longhorn CLI for ARM

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

Downloads the longhornctl binary for ARM64 architecture from GitHub releases and makes it executable. It is then used to perform a preflight check.

```bash
curl -sSfL -o longhornctl https://github.com/longhorn/cli/releases/download/v1.10.0/longhornctl-linux-arm64

chmod +x longhornctl
./longhornctl check preflight
```

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

### Install Preflight Dependencies using Longhorn CLI

Source: https://longhorn.io/docs/1.10.0/v2-data-engine/quick-start

This command installs the necessary preflight dependencies for Longhorn, ensuring the environment is correctly configured. It is recommended to run this before performing the preflight check, especially on certain distributions like SLE Micro which may require a reboot.

```bash
master:~# ./longhornctl install preflight --enable-spdk
```

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

### Install Device Mapper (SUSE/OpenSUSE)

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

Installs the device mapper utilities on SUSE and OpenSUSE distributions using `zypper`. These tools are essential for Longhorn's underlying block device management.

```shell
zypper install device-mapper

```

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

### Install Preflight with Kubeconfig and Image

Source: https://longhorn.io/docs/1.10.0/v2-data-engine/quick-start

This command provides a more complete installation of preflight dependencies, specifying the kubeconfig file and the Longhorn CLI image. This is useful for environments where the default CLI might not be sufficient or when managing specific image versions.

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

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

### Install Cryptsetup (RHEL/CentOS/AmazonLinux2)

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

Installs the `cryptsetup` package on RHEL, CentOS, and Amazon Linux 2 environments via `yum`. This is a prerequisite for enabling encrypted volumes in Longhorn.

```shell
yum install cryptsetup

```

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

### Install open-iscsi on SUSE and openSUSE

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

Installs the open-iscsi package and enables/starts the iscsid service on SUSE and openSUSE Linux distributions. This ensures the iSCSI daemon is running and configured to start on boot. No external dependencies are noted.

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

```

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

### Install NFSv4 Client (SUSE/OpenSUSE)

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

Installs the NFSv4 client on SUSE and OpenSUSE distributions using the `zypper` package manager. This is a requirement for Longhorn's backup and RWX volume capabilities.

```shell
zypper install nfs-client

```

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

### Install open-iscsi on RHEL, CentOS, and EKS (AmazonLinux2)

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

Installs the iscsi-initiator-utils package, configures the initiator name, and enables/starts the iscsid service on RHEL, CentOS, and EKS instances using the AmazonLinux2 image. It includes steps to set a unique InitiatorName.

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

```

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

### Install NFSv4 Client (Debian/Ubuntu)

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

Installs the NFSv4 client userspace daemon and utilities on Debian and Ubuntu systems using the `apt-get` package manager. This is necessary for Longhorn's backup and RWX volume features.

```shell
apt-get install nfs-common

```

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

### Install Linux Kernel Extra Modules (Debian/Ubuntu)

Source: https://longhorn.io/docs/1.10.0/v2-data-engine/quick-start

Installs the necessary Linux kernel extra modules for Debian and Ubuntu systems before loading other kernel modules. This is a prerequisite for SPDK integration.

```bash
apt install -y linux-modules-extra-`uname -r`
```

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

### Verify Preflight Check with Longhorn CLI

Source: https://longhorn.io/docs/1.10.0/v2-data-engine/quick-start

After installing dependencies, this command is used to verify that all preflight environment settings are correct. It provides detailed information on system services, packages, and configurations relevant to Longhorn's operation.

```bash
master:~# ./longhornctl check preflight --enable-spdk
```

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

### Kubernetes CSI Persistent Volume with Longhorn

Source: https://longhorn.io/docs/1.10.0/references/examples

Illustrates the setup of a CSI PersistentVolume and a corresponding PersistentVolumeClaim for use with Longhorn. This example configures a filesystem-based volume with specific Longhorn driver parameters like the number of replicas and stale replica timeout. It also includes a Pod that mounts this volume for data persistence.

```yaml
apiVersion: v1
kind: PersistentVolume
metadata:
  name: longhorn-vol-pv
spec:
  capacity:
    storage: 2Gi
  volumeMode: Filesystem
  accessModes:
    - ReadWriteOnce
  persistentVolumeReclaimPolicy: Delete
  storageClassName: longhorn
  csi:
    driver: driver.longhorn.io
    fsType: ext4
    volumeAttributes:
      numberOfReplicas: '3'
      staleReplicaTimeout: '2880'
    volumeHandle: existing-longhorn-volume
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: longhorn-vol-pvc
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 2Gi
  volumeName: longhorn-vol-pv
  storageClassName: longhorn
---
apiVersion: v1
kind: Pod
metadata:
  name: volume-pv-test
  namespace: default
spec:
  restartPolicy: Always
  containers:
  - name: volume-pv-test
    image: nginx:stable-alpine
    imagePullPolicy: IfNotPresent
    livenessProbe:
      exec:
        command:
          - ls
          - /data/lost+found
      initialDelaySeconds: 5
      periodSeconds: 5
    volumeMounts:
    - name: vol
      mountPath: /data
    ports:
    - containerPort: 80
  volumes:
  - name: vol
    persistentVolumeClaim:
      claimName: longhorn-vol-pvc

```

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

### Create Loop Block Device

Source: https://longhorn.io/docs/1.10.0/v2-data-engine/quick-start

Creates a loopback block device of a specified size (10 GiB in this example) using a file as storage. This is a method to prepare block-type disks for Longhorn's V2 Data Engine when physical disks are unavailable.

```bash
dd if=/dev/zero of=blockfile bs=1M count=10240
losetup -f blockfile

```

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

### Download Longhorn CLI (Shell)

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

Downloads the Longhorn CLI tool (`longhornctl`) for the AMD64 platform using `curl`. This tool is used for managing and checking Longhorn configurations.

```shell
# For AMD64 platform
curl -sSfL -o longhornctl https://github.com/longhorn/cli/releases/download/v1.10.0/longhornctl-linux-amd64

```

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

### Example of Successful Longhorn Pods

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

This output shows a typical list of running pods after a successful Longhorn installation in Kubernetes. It includes core Longhorn components like the UI, manager, driver deployer, CSI plugins, and instance managers, indicating that the storage system is operational.

```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
```

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

### Example: Apply Ingress via stdin and Verify

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

This example demonstrates applying the Ingress manifest directly from standard input and then verifying its creation and accessibility. It includes a curl command to test the authentication by attempting to access the Ingress without credentials and then with correct credentials.

```bash
$ echo "
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: longhorn-ingress
  namespace: longhorn-system
  annotations:
    # type of authentication
    nginx.ingress.kubernetes.io/auth-type: basic
    # prevent the controller from redirecting (308) to HTTPS
    nginx.ingress.kubernetes.io/ssl-redirect: 'false'
    # name of the secret that contains the user/password definitions
    nginx.ingress.kubernetes.io/auth-secret: basic-auth
    # message to display with an appropriate context why the authentication is required
    nginx.ingress.kubernetes.io/auth-realm: 'Authentication Required '
spec:
  rules:
  - http:
      paths:
      - pathType: Prefix
        path: \"/\" 
        backend:
          service:
            name: longhorn-frontend
            port:
              number: 80
" | kubectl -n longhorn-system create -f -
ingress.networking.k8s.io/longhorn-ingress created

$ kubectl -n longhorn-system get ingress
NAME               HOSTS   ADDRESS                                     PORTS   AGE
longhorn-ingress   *       45.79.165.114,66.228.45.37,97.107.142.125   80      2m7s

$ curl -v http://97.107.142.125/
*   Trying 97.107.142.125...
* TCP_NODELAY set
* Connected to 97.107.142.125 (97.107.142.125) port 80 (#0)
> GET / HTTP/1.1
> Host: 97.107.142.125
> User-Agent: curl/7.64.1
> Accept: */*
> 
< HTTP/1.1 401 Unauthorized
< Server: openresty/1.15.8.1
< Date: Fri, 29 May 2020 11:47:33 GMT
< Content-Type: text/html
< Content-Length: 185
< Connection: keep-alive
< WWW-Authenticate: Basic realm="Authentication Required"
< 
<html>
<head><title>401 Authorization Required</title></head>
<body>
<center><h1>401 Authorization Required</h1></center>
<hr><center>openresty/1.15.8.1</center>
</body>
</html>
* Connection #0 to host 97.107.142.125 left intact
* Closing connection 0

$ curl -v http://97.107.142.125/ -u foo:bar
*   Trying 97.107.142.125...
* TCP_NODELAY set
* Connected to 97.107.142.125 (97.107.142.125) port 80 (#0)
* Server auth using Basic with user 'foo'
> GET / HTTP/1.1
> Host: 97.107.142.125
> Authorization: Basic Zm9vOmJhcg==
> User-Agent: curl/7.64.1
> Accept: */*
> 
< HTTP/1.1 200 OK

```

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

### Install open-iscsi on Debian and Ubuntu

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

Installs the open-iscsi package on Debian and Ubuntu-based systems using the apt-get package manager. This is a straightforward installation without additional service management commands.

```shell
apt-get install open-iscsi

```

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

### Install Device Mapper (RHEL/CentOS/AmazonLinux2)

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

Installs the device mapper userspace tools on RHEL, CentOS, and Amazon Linux 2 via `yum`. This framework is fundamental for block device management in Longhorn.

```shell
yum install device-mapper

```

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

### Install NFSv4 Client (RHEL/CentOS/AmazonLinux2)

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

Installs the NFSv4 client utilities on RHEL, CentOS, and Amazon Linux 2 (used in EKS) via the `yum` package manager. This enables Longhorn's NFS-dependent features.

```shell
yum install nfs-utils

```

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

### Check Kubernetes Version using kubectl

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

This snippet demonstrates how to use the `kubectl version` command to check the Kubernetes server and client versions. The server version must be greater than or equal to v1.25 for Longhorn installation.

```bash
kubectl version

```

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

### Example: Create Auth File and Secret

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

Provides a complete example demonstrating the creation of the 'auth' file with credentials and subsequently creating the 'basic-auth' secret in Kubernetes. It includes verification steps by outputting the secret in YAML format.

```bash
$ USER=foo; PASSWORD=bar; echo "${USER}:$(openssl passwd -stdin -apr1 <<< ${PASSWORD})" >> auth
$ cat auth
foo:$apr1$FnyKCYKb$6IP2C45fZxMcoLwkOwf7k0

$ kubectl -n longhorn-system create secret generic basic-auth --from-file=auth
secret/basic-auth created
$ kubectl -n longhorn-system get secret basic-auth -o yaml
apiVersion: v1
data:
  auth: Zm9vOiRhcHIxJEZueUtDWUtiJDZJUDJDNDVmWnhNY29Md2tPd2Y3azAK
kind: Secret
metadata:
  creationTimestamp: "2020-05-29T10:10:16Z"
  name: basic-auth
  namespace: longhorn-system
  resourceVersion: "2168509"
  selfLink: /api/v1/namespaces/longhorn-system/secrets/basic-auth
  uid: 9f66233f-b12f-4204-9c9d-5bcaca794bb7
type: Opaque

```

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

### Install longhornctl Binary (Linux)

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

Installs the downloaded longhornctl binary to the system's PATH, making it executable. This command requires root privileges (`sudo`).

```shell
#!/bin/bash
ARCH="amd64"
sudo install longhornctl-linux-${ARCH} /usr/local/bin/longhornctl
```

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

### Kubernetes Deployment with Longhorn Persistent Volume

Source: https://longhorn.io/docs/1.10.0/references/examples

Provides a Kubernetes example for deploying a stateful application (MySQL in this case) that utilizes Longhorn storage. It defines a Service, a PersistentVolumeClaim requesting storage from Longhorn, and a Deployment that mounts this PVC to the MySQL container. This setup ensures data persistence for the MySQL instance.

```yaml
apiVersion: v1
kind: Service
metadata:
  name: mysql
  labels:
    app: mysql
spec:
  ports:
    - port: 3306
  selector:
    app: mysql
  clusterIP: None
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: mysql-pvc
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: longhorn
  resources:
    requests:
      storage: 2Gi
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: mysql
  labels:
    app: mysql
spec:
  selector:
    matchLabels:
      app: mysql # has to match .spec.template.metadata.labels
  strategy:
    type: Recreate
  template:
    metadata:
      labels:
        app: mysql
    spec:
      restartPolicy: Always
      containers:
      - image: mysql:5.6
        name: mysql
        livenessProbe:
          exec:
            command:
              - ls
              - /var/lib/mysql/lost+found
          initialDelaySeconds: 5
          periodSeconds: 5
        env:
        - name: MYSQL_ROOT_PASSWORD
          value: changeme
        ports:
        - containerPort: 3306
          name: mysql
        volumeMounts:
        - name: mysql-volume
          mountPath: /var/lib/mysql
      volumes:
      - name: mysql-volume
        persistentVolumeClaim:
          claimName: mysql-pvc

```

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

### Retrieve Kubelet Logs (Containerized Installation)

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

This command retrieves logs from the `kubelet` container, typically used when kubelet is running within a container, such as in RKE environments. It's crucial for diagnosing Flexvolume driver problems in such setups.

```bash
docker logs kubelet
```

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

### Download longhornctl Binary (Linux)

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

Downloads the prebuilt longhornctl binary for Linux. Users need to select their architecture (amd64 or arm64). This step requires `curl` to be installed.

```shell
#!/bin/bash
# Choose your architecture (amd64 or arm64).
ARCH="amd64"

# Download the release binary.
curl -LO "https://github.com/longhorn/cli/releases/download/v1.10.0/longhornctl-linux-${ARCH}"
```

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

### Monitor Longhorn Pods on OKD

Source: https://longhorn.io/docs/1.10.0/advanced-resources/os-distro-specific/okd-support

Monitors the creation of pods within the `longhorn-system` namespace on an OKD cluster to track the Longhorn installation progress. This command uses `oc get pods` with the `--watch` flag.

```bash
oc get pods \
  --namespace longhorn-system \
  --watch
```

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

### Apply GitRepo CR and Verify Installation

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

These commands are used to apply the created GitRepo CR and subsequently verify the installation status of Longhorn and related pods. The first command applies the resource definition, while the second monitors the GitRepo status, and the third checks for running Longhorn pods.

```bash
kubectl apply -f longhorn-gitrepo.yaml
```

```bash
kubectl -n fleet-local get gitrepo -w
```

```bash
kubectl -n longhorn-system get pod
```

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

### Install Fleet using Helm

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

These commands add the Fleet Helm chart repository and install the Fleet CRDs and the Fleet application. Ensure Helm v3.0 or later is installed. The installation creates the `cattle-fleet-system` namespace.

```bash
helm repo add fleet https://rancher.github.io/fleet-helm-charts/
helm -n cattle-fleet-system install --create-namespace --wait fleet-crd fleet/fleet-crd
helm -n cattle-fleet-system install --create-namespace --wait fleet fleet/fleet
```

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

### Create HelmChart CR for Longhorn Installation

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

This YAML defines a HelmChart resource to install Longhorn. It specifies the chart name, repository, version, target namespace, and failure policy. Ensure the `spec.failurePolicy` is set to 'abort' for proper error handling.

```yaml
apiVersion: helm.cattle.io/v1
kind: HelmChart
metadata:
  annotations:
    helmcharts.cattle.io/managed-by: helm-controller
  finalizers:
  - wrangler.cattle.io/on-helm-chart-remove
  generation: 1
  name: longhorn-install
  namespace: default
spec:
  version: v1.10.0
  chart: longhorn
  repo: https://charts.longhorn.io
  failurePolicy: abort
  targetNamespace: longhorn-system
  createNamespace: true

```

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

### Download Longhorn OKD Installation File

Source: https://longhorn.io/docs/1.10.0/advanced-resources/os-distro-specific/okd-support

Downloads the `longhorn-okd.yaml` manifest file required for installing Longhorn on OKD clusters. This command uses `wget` and specifies the direct URL to the file.

```bash
wget https://raw.githubusercontent.com/longhorn/longhorn/v1.10.0/deploy/longhorn-okd.yaml
```

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

### Kubernetes Block Volume with Longhorn

Source: https://longhorn.io/docs/1.10.0/references/examples

Demonstrates creating a Kubernetes PersistentVolumeClaim configured for block volume access with Longhorn storage. It also shows a Pod that mounts this block device, suitable for applications requiring raw block device access. Ensure the Longhorn CSI driver is installed and the 'longhorn' StorageClass is available.

```yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: longhorn-block-vol
spec:
  accessModes:
    - ReadWriteOnce
  volumeMode: Block
  storageClassName: longhorn
  resources:
    requests:
      storage: 2Gi
---
apiVersion: v1
kind: Pod
metadata:
  name: block-volume-test
  namespace: default
spec:
  containers:
    - name: block-volume-test
      image: nginx:stable-alpine
      imagePullPolicy: IfNotPresent
      volumeDevices:
        - devicePath: /dev/longhorn/testblk
          name: block-vol
      ports:
        - containerPort: 80
  volumes:
    - name: block-vol
      persistentVolumeClaim:
        claimName: longhorn-block-vol

```

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

### Check NFSv4.2 Kernel Support (Shell)

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

This command checks for NFSv4.2 kernel support, another version compatible with Longhorn's backup features. It's executed by searching the kernel configuration file.

```shell
cat /boot/config-`uname -r`| grep CONFIG_NFS_V4_2

```

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

### Add Longhorn Helm Repository

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

Adds the Longhorn Helm chart repository to your local Helm configuration. This command fetches the Helm charts from the specified URL, making them available for installation.

```bash
helm repo add longhorn https://charts.longhorn.io
```

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

### Configure Longhorn Installation with fleet.yaml

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

This snippet defines the configuration for installing Longhorn using a fleet.yaml file. It specifies the default namespace, parameters to ignore modified CRDs during comparison, and the Helm repository, chart, version, and release name for the Longhorn installation.

```yaml
defaultNamespace: longhorn-system

diff:
  comparePatches:
  - apiVersion: apiextensions.k8s.io/v1
    kind: CustomResourceDefinition
    name: engineimages.longhorn.io
    operations:
    - {"op": "replace", "path": "/status"}
  - apiVersion: apiextensions.k8s.io/v1
    kind: CustomResourceDefinition
    name: nodes.longhorn.io
    operations:
    - {"op": "replace", "path": "/status"}
  - apiVersion: apiextensions.k8s.io/v1
    kind: CustomResourceDefinition
    name: volumes.longhorn.io
    operations:
    - {"op": "replace", "path": "/status"}
  - apiVersion: apiextensions.k8s.io/v1
    kind: CustomResourceDefinition
    name: engines.longhorn.io
    operations:
    - {"op": "replace", "path": "/status"}
  - apiVersion: apiextensions.k8s.io/v1
    kind: CustomResourceDefinition
    name: instancemanagers.longhorn.io
    operations:
    - {"op": "replace", "path": "/status"}
  - apiVersion: apiextensions.k8s.io/v1
    kind: CustomResourceDefinition
    name: replicas.longhorn.io
    operations:
    - {"op": "replace", "path": "/status"}
  - apiVersion: apiextensions.k8s.io/v1
    kind: CustomResourceDefinition
    name: settings.longhorn.io
    operations:
    - {"op": "replace", "path": "/status"}

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

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

### Verify Longhorn Deployment with kubectl

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

These commands help verify the Longhorn installation by checking for active jobs, pods, and HelmChart resources. The output should show completed jobs and running pods in the 'longhorn-system' namespace.

```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.10.0    https://charts.longhorn.io

```

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

### Install Longhorn with Helm (Shell)

Source: https://longhorn.io/docs/1.10.0/deploy/install/airgap

This command demonstrates how to install Longhorn using Helm. It specifies the Helm chart location, the target Kubernetes namespace, and ensures the namespace is created if it doesn't exist.

```bash
helm install longhorn ./chart --namespace longhorn-system --create-namespace
```

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

### Find K3s Data Directory using ps command

Source: https://longhorn.io/docs/1.10.0/advanced-resources/os-distro-specific/csi-on-k3s

This example demonstrates how to find the `--data-dir` argument for K3s by inspecting running processes. This information is crucial for determining the Kubelet root directory on K3s versions prior to v0.10.0.

```bash
$ ps uax | grep k3s
root      4160  0.0  0.0  51420  3948 pts/0    S+   00:55   0:00 sudo /usr/local/bin/k3s server --data-dir /opt/test/kubelet
root      4161 49.0  4.0 259204 164292 pts/0   Sl+  00:55   0:04 /usr/local/bin/k3s server --data-dir /opt/test/kubelet
```

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

### Install Argo CD CLI and Core Components

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

Installs the Argo CD CLI on the workstation and applies the core Argo CD installation manifest to the Kubernetes cluster. Ensure Argo CD CLI is installed and a Kubernetes cluster is accessible.

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

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

### Verify Longhorn Pods

Source: https://longhorn.io/docs/1.10.0/deploy/install/install-with-flux

This command lists all pods in the 'longhorn-system' namespace to verify that the Longhorn components have been deployed successfully and are running.

```bash
kubectl -n longhorn-system get pod

```

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

### Configure V2 Data Engine Prerequisites on Talos Linux

Source: https://longhorn.io/docs/1.10.0/advanced-resources/os-distro-specific/talos-linux-support

This configuration snippet sets up prerequisites for the V2 Data Engine on Talos Linux, including huge pages for memory management and loading specific kernel modules like nvme_tcp and vfio_pci.

```yaml
machine:
  sysctls:
    vm.nr_hugepages: "1024"
  kernel:
    modules:
      - name: nvme_tcp
      - name: vfio_pci
#     - name: uio_pci_generic
```

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

### Install Longhorn with Helm

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

Installs Longhorn version 1.10.0 into the 'longhorn-system' namespace. If the namespace does not exist, it will be created. This command deploys Longhorn components using the Helm package manager.

```bash
helm install longhorn longhorn/longhorn --namespace longhorn-system --create-namespace --version 1.10.0
```

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

### Create GitRepo CR for Longhorn Installation

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

This snippet demonstrates how to create a GitRepo custom resource (CR) using kubectl. This CR is essential for fleet to recognize and manage the Longhorn installation by pointing to the GitOps repository containing the configuration files.

```bash
cat > longhorn-gitrepo.yaml << "EOF"
apiVersion: fleet.cattle.io/v1alpha1
kind: GitRepo
metadata:
  name: longhorn
  namespace: fleet-local
spec:
  repo: https://github.com/your-username/your-gitops-repo.git
  revision: main
  paths:
  - .
EOF
```

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

### Verify longhornctl Installation (Linux)

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

Checks if the longhornctl command is installed correctly and displays its version information.

```shell
longhornctl version
```

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

### Install Longhorn with Helm on OCP/OKD

Source: https://longhorn.io/docs/1.10.0/advanced-resources/os-distro-specific/okd-support

Installs Longhorn using Helm with specific configurations for OpenShift/OKD environments. Requires the `helm` CLI and the Longhorn Helm chart. It sets `openshift.enabled` to true and specifies the `oauthProxy` image repository and tag.

```bash
helm install longhorn longhorn/longhorn \
  --namespace longhorn-system \
  --create-namespace \
  --set openshift.enabled=true \
  --set image.openshift.oauthProxy.repository=quay.io/openshift/origin-oauth-proxy \
  --set image.openshift.oauthProxy.tag=4.18
```

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

### Download Longhorn Manifest

Source: https://longhorn.io/docs/1.10.0/deploy/install/airgap

This command downloads the Longhorn deployment manifest file for version 1.10.0 using wget. Ensure wget is installed on your system. This file is essential for the manual deployment process.

```bash
wget https://raw.githubusercontent.com/longhorn/longhorn/v1.10.0/deploy/longhorn.yaml
```

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

### Display Help for Image Management Scripts

Source: https://longhorn.io/docs/1.10.0/deploy/install/airgap

These commands display the available options and usage instructions for the `save-images.sh` and `load-images.sh` scripts, allowing for customization of image management tasks.

```shell
./save-images.sh --help
./load-images.sh --help
```

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

### Watch Longhorn Pods in longhorn-system Namespace

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

This command monitors the creation and status of pods within the 'longhorn-system' namespace. It's useful for observing the progress of the Longhorn installation.

```bash
kubectl get pods \
--namespace longhorn-system \
--watch
```

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

### Download and Execute Longhorn CLI for ARM

Source: https://longhorn.io/docs/1.10.0/v2-data-engine/quick-start

This snippet shows how to download the Longhorn CLI executable for ARM64 architecture, make it executable, and then run a preflight check. It's essential for verifying system readiness before deploying Longhorn.

```bash
curl -sSfL -o longhornctl https://github.com/longhorn/cli/releases/download/v1.10.0/longhornctl-linux-arm64

chmod +x longhornctl
./longhornctl check preflight --enable-spdk
```

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

### Apply Longhorn OKD Installation Manifest

Source: https://longhorn.io/docs/1.10.0/advanced-resources/os-distro-specific/okd-support

Applies the `longhorn-okd.yaml` manifest file to an OKD cluster to install Longhorn. This command requires `oc` CLI access to the cluster and assumes the manifest file has been downloaded.

```bash
oc apply -f longhorn-okd.yaml
```

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

### Install Longhorn with Kubectl

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

This command applies the Longhorn deployment manifest to a Kubernetes cluster, initiating the installation process. Ensure kubectl is configured to communicate with your cluster.

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

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

### Install Longhorn with Helm using a Custom values.yaml

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

Installs Longhorn using Helm, applying custom default settings defined in a local `values.yaml` file. This method is suitable for more extensive configuration changes.

```bash
helm install longhorn longhorn/longhorn \
  --namespace longhorn-system \
  --create-namespace \
  --values values.yaml
```

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

### Download Longhorn Images List

Source: https://longhorn.io/docs/1.10.0/deploy/install/airgap

This command downloads the list of all required Longhorn images for air gap installations. It's a prerequisite for using the image management scripts.

```shell
wget https://raw.githubusercontent.com/longhorn/longhorn/v1.10.0/deploy/longhorn-images.txt
```

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

### Apply HelmChart CR to Install Longhorn

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

This command applies the HelmChart CR definition to your Kubernetes cluster, initiating the Longhorn installation process. It creates the necessary resources for Helm to manage the deployment.

```bash
$ kubectl apply -f helmchart_repo_install.yaml
helmchart.helm.cattle.io/longhorn-install created

```

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

### Enable and Start iSCSI Daemon using Systemd

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

These commands enable the iSCSI daemon to start automatically at boot or start it for the current session. This is a prerequisite for certain Longhorn functionalities. The `sudo su` command elevates privileges to root.

```bash
sudo su
systemctl enable iscsid
reboot
```

```bash
sudo su
systemctl start iscsid
```

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

### Download Longhorn CLI Tool (AMD64)

Source: https://longhorn.io/docs/1.10.0/v2-data-engine/quick-start

Downloads the Longhorn CLI tool (`longhornctl`) for the AMD64 platform from GitHub releases. This tool is used for checking environment prerequisites and configurations.

```bash
# For AMD64 platform
curl -sSfL -o longhornctl https://github.com/longhorn/cli/releases/download/v1.10.0/longhornctl-linux-amd64
```

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

### Update Helm Repositories

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

Fetches the latest list of charts from all configured Helm repositories, including the newly added Longhorn repository. This ensures you have access to the most recent versions of the charts.

```bash
helm repo update
```

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

### Install Longhorn with Helm and Custom Settings

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

Installs Longhorn using Helm, allowing customization of default settings via the --set flag. This is useful for quick modifications without altering configuration files.

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

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

### Load Kernel Modules (Manual)

Source: https://longhorn.io/docs/1.10.0/v2-data-engine/quick-start

Manually loads the `vfio_pci` and `uio_pci_generic` kernel modules on each Longhorn node. These modules are required for SPDK to function correctly.

```bash
modprobe vfio_pci
modprobe uio_pci_generic
```

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

### Sync Longhorn Application with Argo CD

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

Triggers Argo CD to synchronize the defined Longhorn application with the Kubernetes cluster. This command initiates the deployment of Longhorn based on the `longhorn-application.yaml` manifest.

```bash
argocd app sync longhorn
```

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

### Install Common Snapshot Controller using kubectl

Source: https://longhorn.io/docs/1.10.0/snapshots-and-backups/csi-snapshot-support/enable-csi-snapshot-support

Deploys the common snapshot controller for CSI volume snapshots. It's recommended to update the namespace in the YAML files to an appropriate value like 'kube-system' before installation. This is a one-time operation per cluster.

```bash
kubectl create -k deploy/kubernetes/snapshot-controller
```

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

### Define and Apply Longhorn Application Resource

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

Creates a Kubernetes Application custom resource definition for Longhorn using Argo CD. This manifest specifies the chart, repository, version, and Helm values for the Longhorn installation.

```yaml
cat > longhorn-application.yaml <<EOF
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: longhorn
  namespace: argocd
spec:
  syncPolicy:
    syncOptions:
      - CreateNamespace=true
  project: default
  sources:
    - chart: longhorn
      repoURL: https://charts.longhorn.io/
      targetRevision: v1.10.0 # Replace with the Longhorn version you'd like to install or upgrade to
      helm:
        values: |
          preUpgradeChecker:
            jobEnabled: false
  destination:
    server: https://kubernetes.default.svc
    namespace: longhorn-system
EOF
kubectl apply -f longhorn-application.yaml
```

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

### Configure Huge Pages (Manual)

Source: https://longhorn.io/docs/1.10.0/v2-data-engine/quick-start

Configures 2 MiB-sized huge pages on each Longhorn node, allocating a total of 2 GiB. This is crucial for SPDK's performance optimizations and memory overhead reduction.

```bash
echo 1024 > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages
```

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

### Bootstrap Flux with GitHub CLI

Source: https://longhorn.io/docs/1.10.0/deploy/install/install-with-flux

This command bootstraps the Flux GitOps tool by connecting it to a GitHub repository. It requires a GitHub personal access token (PAT) and specifies the repository owner, name, branch, and path within the repository. The `--personal` flag indicates a personal repository.

```bash
export GITHUB_TOKEN=<gh-token>
flux bootstrap github \
  --token-auth \
  --owner=<github_username> \
  --repository=<github_repo_name> \
  --branch=<branch_name> \
  --path=<folder_path_within_repo> \
  --personal

```

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

### Create Longhorn Namespace

Source: https://longhorn.io/docs/1.10.0/deploy/install/airgap

This command creates a dedicated Kubernetes namespace named 'longhorn-system' for deploying Longhorn components. This helps in organizing and managing Longhorn resources separately from other applications.

```bash
kubectl create namespace longhorn-system
```

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

### Upgrade Talos Linux Node Preserving Data (Pre-v1.8.x)

Source: https://longhorn.io/docs/1.10.0/advanced-resources/os-distro-specific/talos-linux-support

This command upgrades a Talos Linux node using a specific installer image while preserving ephemeral data. The `--preserve` option is critical to prevent the loss of Longhorn replicas stored on the node.

```bash
talosctl upgrade --nodes 10.20.30.40 --image ghcr.io/siderolabs/installer:v1.7.6 --preserve
```

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

### Install Talos Linux System Extensions for Longhorn

Source: https://longhorn.io/docs/1.10.0/advanced-resources/os-distro-specific/talos-linux-support

This configuration snippet enables official system extensions for Longhorn on Talos Linux. It ensures that necessary tools like iscsid daemon and fstrim are available on all nodes for persistent volume operations and volume trimming.

```yaml
customization:
  systemExtensions:
    officialExtensions:
      - siderolabs/iscsi-tools
      - siderolabs/util-linux-tools
```

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

### Get OKD Node Names

Source: https://longhorn.io/docs/1.10.0/advanced-resources/os-distro-specific/okd-support

Retrieves a list of all node names within an OpenShift/OKD cluster. This command is useful for identifying target nodes for debugging or configuration.

```bash
oc get nodes --no-headers | awk '{print $1}'
```
Tokens:
Raw