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
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
EOFThat’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-frontendIP 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.13+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”.