15 Longhorn #
Longhorn is a lightweight, reliable and user-friendly distributed block storage system designed for Kubernetes. As an open source project, Longhorn was initially developed by Rancher Labs and is currently incubated under the CNCF.
15.1 Prerequisites #
If you are following this guide, it assumes that you have the following already available:
At least one host with SLE Micro 5.5 installed; this can be physical or virtual
A Kubernetes cluster installed; either K3s or RKE2
Helm
15.2 Manual installation of Longhorn #
15.2.1 Installing Open-iSCSI #
A core requirement of deploying and using Longhorn is the installation of the open-iscsi
package and the iscsid
daemon running on all Kubernetes nodes.
This is necessary, since Longhorn relies on iscsiadm
on the host to provide persistent volumes to Kubernetes.
Let’s install it:
transactional-update pkg install open-iscsi
It is important to note that once the operation is completed, the package is only installed into a new snapshot as SLE Micro is an immutable operating system.
In order to load it and for the iscsid
daemon to start running, we must reboot into that new snapshot that we just created.
Issue the reboot command when you are ready:
reboot
For additional help installing open-iscsi, refer to the official Longhorn documentation.
15.2.2 Installing Longhorn #
There are several ways to install Longhorn on your Kubernetes clusters. This guide will follow through the Helm installation, however feel free to follow the official documentation if another approach is desired.
Add the Longhorn Helm repository:
helm repo add longhorn https://charts.longhorn.io
Fetch the latest charts from the repository:
helm repo update
Install Longhorn in the longhorn-system namespace:
helm install longhorn longhorn/longhorn --namespace longhorn-system --create-namespace --version 1.6.1
Confirm that the deployment succeeded:
kubectl -n longhorn-system get pods
localhost:~ # kubectl -n longhorn-system get pod NAMESPACE NAME READY STATUS RESTARTS AGE longhorn-system longhorn-ui-5fc9fb76db-z5dc9 1/1 Running 0 90s longhorn-system longhorn-ui-5fc9fb76db-dcb65 1/1 Running 0 90s longhorn-system longhorn-manager-wts2v 1/1 Running 1 (77s ago) 90s longhorn-system longhorn-driver-deployer-5d4f79ddd-fxgcs 1/1 Running 0 90s longhorn-system instance-manager-a9bf65a7808a1acd6616bcd4c03d925b 1/1 Running 0 70s longhorn-system engine-image-ei-acb7590c-htqmp 1/1 Running 0 70s longhorn-system csi-attacher-5c4bfdcf59-j8xww 1/1 Running 0 50s longhorn-system csi-provisioner-667796df57-l69vh 1/1 Running 0 50s longhorn-system csi-attacher-5c4bfdcf59-xgd5z 1/1 Running 0 50s longhorn-system csi-provisioner-667796df57-dqkfr 1/1 Running 0 50s longhorn-system csi-attacher-5c4bfdcf59-wckt8 1/1 Running 0 50s longhorn-system csi-resizer-694f8f5f64-7n2kq 1/1 Running 0 50s longhorn-system csi-snapshotter-959b69d4b-rp4gk 1/1 Running 0 50s longhorn-system csi-resizer-694f8f5f64-r6ljc 1/1 Running 0 50s longhorn-system csi-resizer-694f8f5f64-k7429 1/1 Running 0 50s longhorn-system csi-snapshotter-959b69d4b-5k8pg 1/1 Running 0 50s longhorn-system csi-provisioner-667796df57-n5w9s 1/1 Running 0 50s longhorn-system csi-snapshotter-959b69d4b-x7b7t 1/1 Running 0 50s longhorn-system longhorn-csi-plugin-bsc8c 3/3 Running 0 50s
15.3 Creating Longhorn volumes #
Longhorn utilizes Kubernetes resources called StorageClass
in order to automatically provision PersistentVolume
objects for pods.
Think of StorageClass
as a way for administrators to describe the classes or profiles of storage they offer.
Let’s create a StorageClass
with some default options:
kubectl apply -f - <<EOF kind: StorageClass apiVersion: storage.k8s.io/v1 metadata: name: longhorn-example provisioner: driver.longhorn.io allowVolumeExpansion: true parameters: numberOfReplicas: "3" staleReplicaTimeout: "2880" # 48 hours in minutes fromBackup: "" fsType: "ext4" EOF
Now that we have our StorageClass
in place, we need a PersistentVolumeClaim
referencing it.
A PersistentVolumeClaim
(PVC) is a request for storage by a user. PVCs consume PersistentVolume
resources.
Claims can request specific sizes and access modes (e.g., they can be mounted once read/write or many times read-only).
Let’s create a PersistentVolumeClaim
:
kubectl apply -f - <<EOF apiVersion: v1 kind: PersistentVolumeClaim metadata: name: longhorn-volv-pvc namespace: longhorn-system spec: accessModes: - ReadWriteOnce storageClassName: longhorn-example resources: requests: storage: 2Gi EOF
That’s it! Once we have the PersistentVolumeClaim
created, we can proceed with attaching it to a Pod
.
When the Pod
is deployed, Kubernetes creates the Longhorn volume and binds it to the Pod
if storage is available.
kubectl apply -f - <<EOF apiVersion: v1 kind: Pod metadata: name: volume-test namespace: longhorn-system spec: containers: - name: volume-test image: nginx:stable-alpine imagePullPolicy: IfNotPresent volumeMounts: - name: volv mountPath: /data ports: - containerPort: 80 volumes: - name: volv persistentVolumeClaim: claimName: longhorn-volv-pvc EOF
The concept of storage in Kubernetes is a complex, but important topic. We briefly mentioned some of the most common Kubernetes resources, however, we suggest to familiarize yourself with the terminology documentation that Longhorn offers.
In this example, the result should look something like this:
localhost:~ # kubectl get storageclass NAME PROVISIONER RECLAIMPOLICY VOLUMEBINDINGMODE ALLOWVOLUMEEXPANSION AGE longhorn (default) driver.longhorn.io Delete Immediate true 12m longhorn-example driver.longhorn.io Delete Immediate true 24s localhost:~ # kubectl get pvc -n longhorn-system NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE longhorn-volv-pvc Bound pvc-f663a92e-ac32-49ae-b8e5-8a6cc29a7d1e 2Gi RWO longhorn-example 54s localhost:~ # kubectl get pods -n longhorn-system NAME READY STATUS RESTARTS AGE csi-attacher-5c4bfdcf59-qmjtz 1/1 Running 0 14m csi-attacher-5c4bfdcf59-s7n65 1/1 Running 0 14m csi-attacher-5c4bfdcf59-w9xgs 1/1 Running 0 14m csi-provisioner-667796df57-fmz2d 1/1 Running 0 14m csi-provisioner-667796df57-p7rjr 1/1 Running 0 14m csi-provisioner-667796df57-w9fdq 1/1 Running 0 14m csi-resizer-694f8f5f64-2rb8v 1/1 Running 0 14m csi-resizer-694f8f5f64-z9v9x 1/1 Running 0 14m csi-resizer-694f8f5f64-zlncz 1/1 Running 0 14m csi-snapshotter-959b69d4b-5dpvj 1/1 Running 0 14m csi-snapshotter-959b69d4b-lwwkv 1/1 Running 0 14m csi-snapshotter-959b69d4b-tzhwc 1/1 Running 0 14m engine-image-ei-5cefaf2b-hvdv5 1/1 Running 0 14m instance-manager-0ee452a2e9583753e35ad00602250c5b 1/1 Running 0 14m longhorn-csi-plugin-gd2jx 3/3 Running 0 14m longhorn-driver-deployer-9f4fc86-j6h2b 1/1 Running 0 15m longhorn-manager-z4lnl 1/1 Running 0 15m longhorn-ui-5f4b7bbf69-bln7h 1/1 Running 3 (14m ago) 15m longhorn-ui-5f4b7bbf69-lh97n 1/1 Running 3 (14m ago) 15m volume-test 1/1 Running 0 26s
15.4 Accessing the UI #
If you installed Longhorn with kubectl or Helm, you need to set up an Ingress controller to allow external traffic into the cluster. Authentication is not enabled by default. If the Rancher catalog app was used, Rancher automatically created an Ingress controller with access control (the rancher-proxy).
Get the Longhorn’s external service IP address:
kubectl -n longhorn-system get svc
Once you have retrieved the
longhorn-frontend
IP address, you can start using the UI by navigating to it in your browser.
15.5 Installing with Edge Image Builder #
SUSE Edge is using Chapter 9, Edge Image Builder in order to customize base SLE Micro OS images. We are going to demonstrate how to do so for provisioning an RKE2 cluster with Longhorn on top of it.
Let’s create the definition file:
export CONFIG_DIR=$HOME/eib mkdir -p $CONFIG_DIR cat << EOF > $CONFIG_DIR/iso-definition.yaml apiVersion: 1.0 image: imageType: iso baseImage: SLE-Micro.x86_64-5.5.0-Default-SelfInstall-GM2.install.iso arch: x86_64 outputImageName: eib-image.iso kubernetes: version: v1.28.10+rke2r1 helm: charts: - name: longhorn version: 1.6.1 repositoryName: longhorn targetNamespace: longhorn-system createNamespace: true installationNamespace: kube-system repositories: - name: longhorn url: https://charts.longhorn.io operatingSystem: packages: sccRegistrationCode: <reg-code> packageList: - open-iscsi users: - username: root encryptedPassword: \$6\$jHugJNNd3HElGsUZ\$eodjVe4te5ps44SVcWshdfWizrP.xAyd71CVEXazBJ/.v799/WRCBXxfYmunlBO2yp1hm/zb4r8EmnrrNCF.P/ EOF
Customizing any of the Helm chart values is possible via a separate file provided under helm.charts[].valuesFile
.
Refer to the upstream documentation for details.
Let’s build the image:
podman run --rm --privileged -it -v $CONFIG_DIR:/eib registry.suse.com/edge/edge-image-builder:1.0.2 build --definition-file $CONFIG_DIR/iso-definition.yaml
After the image is built, you can use it to install your OS on a physical or virtual host.
Once the provisioning is complete, you are able to log in to the system using the root:eib
credentials pair.
Ensure that Longhorn has been successfully deployed:
localhost:~ # /var/lib/rancher/rke2/bin/kubectl --kubeconfig /etc/rancher/rke2/rke2.yaml -n longhorn-system get pods NAME READY STATUS RESTARTS AGE csi-attacher-5c4bfdcf59-qmjtz 1/1 Running 0 103s csi-attacher-5c4bfdcf59-s7n65 1/1 Running 0 103s csi-attacher-5c4bfdcf59-w9xgs 1/1 Running 0 103s csi-provisioner-667796df57-fmz2d 1/1 Running 0 103s csi-provisioner-667796df57-p7rjr 1/1 Running 0 103s csi-provisioner-667796df57-w9fdq 1/1 Running 0 103s csi-resizer-694f8f5f64-2rb8v 1/1 Running 0 103s csi-resizer-694f8f5f64-z9v9x 1/1 Running 0 103s csi-resizer-694f8f5f64-zlncz 1/1 Running 0 103s csi-snapshotter-959b69d4b-5dpvj 1/1 Running 0 103s csi-snapshotter-959b69d4b-lwwkv 1/1 Running 0 103s csi-snapshotter-959b69d4b-tzhwc 1/1 Running 0 103s engine-image-ei-5cefaf2b-hvdv5 1/1 Running 0 109s instance-manager-0ee452a2e9583753e35ad00602250c5b 1/1 Running 0 109s longhorn-csi-plugin-gd2jx 3/3 Running 0 103s longhorn-driver-deployer-9f4fc86-j6h2b 1/1 Running 0 2m28s longhorn-manager-z4lnl 1/1 Running 0 2m28s longhorn-ui-5f4b7bbf69-bln7h 1/1 Running 3 (2m7s ago) 2m28s longhorn-ui-5f4b7bbf69-lh97n 1/1 Running 3 (2m10s ago) 2m28s
This installation will not work for completely air-gapped environments. In those cases, please refer to Section 21.8, “Longhorn Installation”.