K3S et le stockage avec Longhorn

Pour optimiser l’utilisation d’un cluster Kubernetes avec des services nécessitant du stockage, une préparation adéquate est essentielle.

Pré-requis avant installation#

Kubernetes 1.28+ ;
Au moins 2 Go de mémoire vive ;
Paquet open-iscsi installé et openiscsid fonctionnel ;
Un disque dédié pour Longhorn (si ce n’est pas possible, je vous donnerai la solution).

Créez un dossier dans /opt pour Longhorn :

sudo mkdir -p /opt/longhorn
sudo chown -R root:root /opt/longhorn
sudo chmod 755 /opt/longhorn

Installation de Longhorn via un manifest#

Grâce à un seul fichier .yaml, Longhorn sera installé ainsi que toutes ses dépendances. Récupérez le manifest depuis le dépôt GitHub, créez le namespace longhorn-system, modifiez le manifest puis lancez la commande kubectl apply pour déployer les outils.

La modification du manifest vous permet de spécifier le chemin sous lequel seront stockés les volumes. Pour ça, ouvrez le fichier longhorn.yaml et recherchez la ligne “# Source: longhorn/templates/default-setting.yaml”. Dans le bloc yaml, saisissez l’entrée et la valeur désirée (pour ma part : default-data-path: /opt/longhorn/.

wget https://raw.githubusercontent.com/longhorn/longhorn/v1.9.1/deploy/longhorn.yaml
vim longhorn.yaml
# recherche la ligne --- # Source: longhorn/templates/default-setting.yaml et modifiez le bloc suivant :
"data:
  default-setting.yaml: |-"
# avec : default-data-path: /opt/longhorn

## exemple complet :
# Source: longhorn/templates/default-setting.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: longhorn-default-setting
  namespace: longhorn-system
  labels:
    app.kubernetes.io/name: longhorn
    app.kubernetes.io/instance: longhorn
    app.kubernetes.io/version: v1.9.1
data:
  default-setting.yaml: |-
    priority-class: longhorn-critical
    disable-revision-counter: true
    default-data-path: /opt/longhorn/

# enregistez les modifications et fermez le fichier.

kubectl create namespace longhorn-system
kubectl apply -f longhorn.yaml

Lorsque le manifest sera appliqué, patientez quelques instants que les pods se créent, démarrent et que le service soit rendu. Lorsque tout est en place, voici le résultat que vous devriez avoir :

kubectl get pods -n longhorn-system

NAME                                                READY   STATUS    RESTARTS        AGE
csi-attacher-6cc66dfc7-j45l7                        1/1     Running   0               2m40s
csi-attacher-6cc66dfc7-ng8kr                        1/1     Running   0               2m40s
csi-attacher-6cc66dfc7-ztfxx                        1/1     Running   0               2m40s
csi-provisioner-bf9f5dcf-6scg9                      1/1     Running   0               2m40s
csi-provisioner-bf9f5dcf-jksmn                      1/1     Running   0               2m40s
csi-provisioner-bf9f5dcf-p5f7v                      1/1     Running   0               2m40s
csi-resizer-79f94cf664-hzwqt                        1/1     Running   0               2m40s
csi-resizer-79f94cf664-nrrs2                        1/1     Running   0               2m40s
csi-resizer-79f94cf664-pmd5k                        1/1     Running   0               2m40s
csi-snapshotter-55f6bf5866-dhgz9                    1/1     Running   0               2m40s
csi-snapshotter-55f6bf5866-hgt2n                    1/1     Running   0               2m40s
csi-snapshotter-55f6bf5866-q4z9l                    1/1     Running   0               2m40s
engine-image-ei-b4bcf0a5-x2pxh                      1/1     Running   0               3m22s
instance-manager-b768354845c8af1e22ce96efac47843c   1/1     Running   0               2m52s
longhorn-csi-plugin-f7vr6                           3/3     Running   0               2m40s
longhorn-driver-deployer-6d5c74866f-79bq8           1/1     Running   0               3m49s
longhorn-manager-7xrgh                              2/2     Running   1 (3m30s ago)   3m49s
longhorn-ui-6cb46c8ff9-6fs92                        1/1     Running   0               3m49s
longhorn-ui-6cb46c8ff9-t6wh2                        1/1     Running   0               3m49s

Tous les pods doivent être dans l’état “Running”.

En cas de mauvaise configuration#

Si le chemin n’a pas été modifié dans le manifest de déploiement, vous pouvez appliquer un patch via les paramètres de Longhorn. Soyez prudent, car cette opération peut entraîner une perte de données, un redémarrage des pods et une indisponibilité du stockage pour vos pods. Il est donc essentiel d’être très attentif avant d’exécuter cette commande.

La modification s’appliquera uniquement aux nouveaux volumes créés avec Longhorn, tandis que les volumes existants ne seront pas déplacés.

kubectl -n longhorn-system patch settings.longhorn.io default-data-path -p '{"spec":{"value":"/opt/longhorn"}}' --type=merge

Remplacez le chemin /opt/longhorn par votre destination.

Pour valider l’opération, récupérez la configuration avec la commande kubectl -n longhorn-system get settings.longhorn.io default-data-path -o yaml. Vous devriez avoir ce genre de sortie :

kubectl -n longhorn-system get settings.longhorn.io default-data-path -o yaml

apiVersion: longhorn.io/v1beta2
kind: Setting
metadata:
  annotations:
    longhorn.io/configmap-resource-version: "26750"
  creationTimestamp: "2025-08-21T17:12:31Z"
  generation: 1
  name: default-data-path
  namespace: longhorn-system
  resourceVersion: "27082"
  uid: 92b6fe01-019f-4a9f-9cd2-868779412f84
status:
  applied: true
value: /opt/longhorn/

Place aux tests#

L’outil en place, c’est une chose, maintenant, il est nécessaire de le tester. Avec le manifest ci-dessous, un pod sera créé dans le namespace longhorn-test, avec un volume de 1 Go. Copiez-collez le contenu que je vous propose dans un fichier (par exemple, longhorn-test.yaml) et appliquez-le (kubectl apply -f longhorn.yaml).

apiVersion: v1
kind: Namespace
metadata:
  name: longhorn-test
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: demo-longhorn-pvc
  namespace: longhorn-test
spec:
  storageClassName: longhorn
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 1Gi
---
apiVersion: v1
kind: Pod
metadata:
  name: demo-longhorn-pod
  namespace: longhorn-test
spec:
  containers:
  - name: busybox
    image: busybox
    command: ["sh", "-c", "while true; do echo $(date) >> /data/log.txt; sleep 10; done"]
    volumeMounts:
    - name: data
      mountPath: /data
  volumes:
  - name: data
    persistentVolumeClaim:
      claimName: demo-longhorn-pvc

Voici les résultats attendus quelques instants après le déploiement :

kubectl apply -f longhorn-test.yaml
namespace/longhorn-test created
persistentvolumeclaim/demo-longhorn-pvc created
pod/demo-longhorn-pod created

kubectl exec -n longhorn-test -it demo-longhorn-pod -- cat /data/log.txt
Thu Aug 21 18:33:42 UTC 2025
Thu Aug 21 18:33:52 UTC 2025
Thu Aug 21 18:34:02 UTC 2025
Thu Aug 21 18:34:12 UTC 2025
Thu Aug 21 18:34:22 UTC 2025
Thu Aug 21 18:34:32 UTC 2025
Thu Aug 21 18:34:42 UTC 2025

Dans le serveur k3s, à l’emplacement cible (ici, /opt/longhorn/), vous trouverez dans le dossier replicas les PVC de vos pods.

root@vps-1:~# ls -alh /opt/longhorn/
total 16K
drwxr-xr-x 3 root root 4.0K Aug 21 17:13 .
drwxr-xr-x 4 root root 4.0K Aug 21 16:50 ..
-rw-r--r-- 1 root root  110 Aug 21 17:13 longhorn-disk.cfg
drwxr-xr-x 3 root root 4.0K Aug 21 18:33 replicas
root@vps-1:~# ls -alh /opt/longhorn/replicas/
total 12K
drwxr-xr-x 3 root root 4.0K Aug 21 18:33 .
drwxr-xr-x 3 root root 4.0K Aug 21 17:13 ..
drwx------ 2 root root 4.0K Aug 21 18:33 pvc-2a48dbf5-1e6b-46ba-b573-b68d43f45e79-f1ba2a21

N’oubliez pas d’arrêter le test en faisant kubectl delete -f longhorn-test.yaml.

Quelques astuces#

Mise à jour de Longhorn#

Vérifiez la matrice de compatibilité sur le site officiel, et assurez-vous que votre version actuelle peut supporter une mise à jour vers une version supérieure. Ensuite, déployez le manifest correspondant à la nouvelle version désirée : kubectl apply -f https://raw.githubusercontent.com/longhorn/longhorn/v<numero>/deploy/longhorn.yaml

Vérifier l’état de service#

En ligne de commande, saisissez la commande suivante : kubectl -n longhorn-system get nodes.longhorn.io

Le résultat doit être le suivant :

kubectl -n longhorn-system get nodes.longhorn.io
NAME           READY   ALLOWSCHEDULING   SCHEDULABLE   AGE
nomdunode      True    true              True          90m

Via l’interface web, cliquez sur “UI”, puis sur l’onglet “Node” - un panneau vous montrera toutes les informations nécessaires.

Modifier la taille d’un PVC#

En ligne de commande, saisissez la commande kubectl get pvc -n <nom_namespace> && kubectl edit -n <nom_namespace> pvc <nom_pvc>, et modifiez la valeur dans la ligne spec.resources.requests.storage. Le redimensionnement à chaud est pris en compte et sera instantané.