Longhorn

Longhorn est un système de stockage bloc distribué cloud-native pour Kubernetes, développé par Rancher (SUSE) et projet CNCF Incubating depuis novembre 2021. Il crée un volume par PVC en répliquant les données sur plusieurs nœuds via un moteur de volume léger. Son installation est simple (Helm ou manifest), son UI permet de gérer les volumes, snapshots et backups sans kubectl, et il s'intègre nativement avec les clusters k3s, RKE2 et tout cluster K8s standard.

Longhorn est le choix naturel pour les clusters homelab, edge et mid-size en production : il ne nécessite pas de matériel spécialisé, fonctionne sur des disques ordinaires, et offre backup automatique vers S3 ou NFS.

Informations essentielles

Origine : Rancher / SUSE → CNCF  ·  Licence : Apache 2.0  ·  Architectures : x86_64, ARM64

Liens : Site officiel  ·  Documentation  ·  GitHub  ·  Releases

Support : Les 3 dernières versions mineures sont maintenues. Vérifier la matrice de compatibilité Kubernetes avant mise à jour.

Stack par défaut

Composants

Prérequis

Installer les dépendances OS

# Ubuntu / Debian
sudo apt-get install -y open-iscsi nfs-common
sudo systemctl enable --now iscsid

# Rocky Linux / AlmaLinux / RHEL
sudo dnf install -y iscsi-initiator-utils nfs-utils
sudo systemctl enable --now iscsid

Vérifier les prérequis avec le script officiel

curl -sSfL \
  https://raw.githubusercontent.com/longhorn/longhorn/v1.7.0/scripts/environment_check.sh | bash

Installation

Via Helm (recommandé)

helm repo add longhorn https://charts.longhorn.io
helm repo update

helm install longhorn longhorn/longhorn \
  --namespace longhorn-system \
  --create-namespace \
  --version 1.7.0

# Vérifier (attendre ~2 min)
kubectl -n longhorn-system rollout status deploy/longhorn-ui
kubectl get pods -n longhorn-system

En faire la StorageClass par défaut

kubectl patch storageclass longhorn \
  -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'

kubectl get storageclass

Accéder à l'UI

kubectl -n longhorn-system port-forward svc/longhorn-frontend 8080:80
# Ouvrir http://localhost:8080

Vérification de l'installation

# 1. Tous les pods doivent être Running
kubectl get pods -n longhorn-system
# Composants clés : longhorn-manager (DaemonSet), longhorn-ui, csi-attacher,
#                   csi-provisioner, engine-image-*, instance-manager-*

# 2. Vérifier les nœuds Longhorn et l'espace détecté
kubectl get nodes.longhorn.io -n longhorn-system
# Chaque nœud doit être schedulable=true avec de l'espace disponible

# 3. Vérifier le CSI driver
kubectl get csidriver | grep longhorn
kubectl get pods -n longhorn-system | grep csi

# 4. Vérifier la StorageClass
kubectl get storageclass longhorn

# 5. Vérifier les disques configurés sur un nœud
kubectl get node.longhorn.io <node-name> -n longhorn-system -o yaml | grep -A5 disks

Pièges courants à l'installation

Premier test de bout en bout

# test-longhorn.yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: test-longhorn-pvc
  namespace: default
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: longhorn
  resources:
    requests:
      storage: 1Gi
---
apiVersion: v1
kind: Pod
metadata:
  name: test-longhorn
  namespace: default
spec:
  containers:
  - name: writer
    image: busybox
    command: ["/bin/sh", "-c"]
    args:
    - |
      echo "Longhorn OK $(date)" > /data/test.txt
      cat /data/test.txt
      df -h /data
      sleep 3600
    volumeMounts:
    - name: data
      mountPath: /data
  volumes:
  - name: data
    persistentVolumeClaim:
      claimName: test-longhorn-pvc

kubectl apply -f test-longhorn.yaml

# Suivre le provisionnement
kubectl get pvc test-longhorn-pvc -w
# Pending → Bound (30-60s, Longhorn crée les réplicas sur les nœuds)

kubectl logs test-longhorn
# Doit afficher "Longhorn OK <date>" + df avec ~1G

# Vérifier le volume dans l'UI Longhorn ou via kubectl
kubectl get volumes -n longhorn-system | grep test-longhorn
# Doit afficher le volume avec replica count = 3 (ou votre valeur par défaut)

# Test de persistance : supprimer et recréer le pod
kubectl delete pod test-longhorn
kubectl apply -f - <<EOF
apiVersion: v1
kind: Pod
metadata:
  name: test-longhorn-verify
spec:
  containers:
  - name: reader
    image: busybox
    command: ["/bin/sh", "-c", "cat /data/test.txt"]
    volumeMounts:
    - name: data
      mountPath: /data
  volumes:
  - name: data
    persistentVolumeClaim:
      claimName: test-longhorn-pvc
  restartPolicy: Never
EOF
kubectl logs test-longhorn-verify
# Doit afficher la même ligne écrite précédemment (persistance vérifiée)

# Nettoyage
kubectl delete -f test-longhorn.yaml
kubectl delete pod test-longhorn-verify

Utilisation

PVC avec Longhorn

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: data-longhorn
  namespace: production
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: longhorn
  resources:
    requests:
      storage: 10Gi

StorageClass personnalisée (facteur de réplication)

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: longhorn-2replicas
provisioner: driver.longhorn.io
parameters:
  numberOfReplicas: "2"
  staleReplicaTimeout: "2880"   # 48h en minutes
  fsType: ext4
reclaimPolicy: Delete
allowVolumeExpansion: true

Snapshots et backups

Snapshot manuel

apiVersion: snapshot.storage.k8s.io/v1
kind: VolumeSnapshot
metadata:
  name: data-snapshot-1
  namespace: production
spec:
  volumeSnapshotClassName: longhorn
  source:
    persistentVolumeClaimName: data-longhorn

Configurer un backup target S3

kubectl create secret generic longhorn-s3-secret \
  --from-literal=AWS_ACCESS_KEY_ID=<key> \
  --from-literal=AWS_SECRET_ACCESS_KEY=<secret> \
  --from-literal=AWS_ENDPOINTS=https://s3.eu-west-1.amazonaws.com \
  -n longhorn-system

Dans l'UI : Settings → Backup Target → s3://mon-bucket@eu-west-1/longhorn

Backup récurrent

apiVersion: longhorn.io/v1beta2
kind: RecurringJob
metadata:
  name: daily-backup
  namespace: longhorn-system
spec:
  cron: "0 2 * * *"    # Chaque nuit à 2h
  task: backup
  groups:
  - default
  retain: 7             # Garder 7 backups
  concurrency: 1

Mise à jour

helm repo update

helm upgrade longhorn longhorn/longhorn \
  --namespace longhorn-system \
  --version 1.7.0

kubectl -n longhorn-system rollout status deploy/longhorn-manager

Longhorn met à jour sans interruption de service si les volumes ont plusieurs réplicas. Lire les notes de migration avant chaque upgrade majeur.

Troubleshooting

# État général
kubectl get pods -n longhorn-system
kubectl get volumes -n longhorn-system

# Logs du manager
kubectl logs -n longhorn-system -l app=longhorn-manager --tail=100

# Describe un volume bloqué
kubectl describe lhv <volume-name> -n longhorn-system

# Espace disponible par nœud
kubectl get nodes.longhorn.io -n longhorn-system

PVC bloqué en Pending

kubectl describe pvc <nom> -n <namespace>
# Events : manque d'espace ou nœud indisponible

# Vérifier l'espace sur les nœuds
kubectl get nodes.longhorn.io -n longhorn-system

Volume en Degraded

# Vérifier les réplicas
kubectl get replicas -n longhorn-system | grep <volume-name>

# Réactiver le scheduling sur un nœud
kubectl edit node.longhorn.io/<node-name> -n longhorn-system
# allowScheduling: true

Commandes utiles

# Lister les volumes Longhorn
kubectl get volumes -n longhorn-system

# Lister les nœuds et leur espace
kubectl get nodes.longhorn.io -n longhorn-system

# Lister les backups
kubectl get backups -n longhorn-system

# Lister les snapshots
kubectl get snapshots -n longhorn-system

# Désinstaller Longhorn (préparation requise : voir doc officielle)
kubectl -n longhorn-system patch setting deleting-confirmation-flag --type merge \
  -p '{"value":"true"}'
helm uninstall longhorn -n longhorn-system

Ressources

• Documentation officielle : https://longhorn.io/docs/latest/
• Prérequis d'installation : https://longhorn.io/docs/latest/deploy/install/#installation-requirements
• Backup et restauration : https://longhorn.io/docs/latest/snapshots-and-backups/
• GitHub : https://github.com/longhorn/longhorn
• Releases : https://github.com/longhorn/longhorn/releases