homelab/docs/03-longhorn.md

03 — Longhorn Distributed Storage

Datum: 2026-03-17 Version: Longhorn v1.11.1 (Helm Chart 1.11.1) Namespace: longhorn-system

---

Übersicht

Longhorn ist ein cloud-natives, verteiltes Block-Storage-System für Kubernetes. Es repliziert Volumes über mehrere Nodes und bietet Snapshots, Backups und eine Web-UI.

---

Voraussetzungen

Helm installieren

Helm war nicht vorhanden und wurde installiert:

curl -fsSL https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
# → helm installed into /usr/local/bin/helm
# Version: v3.20.1

Kubeconfig einrichten

mkdir -p ~/.kube
cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
chmod 600 ~/.kube/config

---

Installation

1. Helm Repository hinzufügen

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

Ausgabe:

"longhorn" has been added to your repositories
...Successfully got an update from the "longhorn" chart repository

2. Namespace erstellen

kubectl create namespace longhorn-system

3. Longhorn per Helm installieren

helm install longhorn longhorn/longhorn \
  --namespace longhorn-system \
  --set defaultSettings.defaultReplicaCount=2 \
  --wait \
  --timeout 10m

Parameter:

• defaultReplicaCount=2: Jedes Volume wird auf 2 von 3 Nodes repliziert (ausreichend für 3-Node-Cluster)

Ausgabe:

NAME: longhorn
LAST DEPLOYED: Tue Mar 17 08:42:26 2026
NAMESPACE: longhorn-system
STATUS: deployed
REVISION: 1
APP VERSION: v1.11.1

---

Pod-Status nach Installation

kubectl get pods -n longhorn-system -o wide

Alle 27 Pods im Status Running:

Pod-Gruppe	Anzahl	Nodes
longhorn-manager	3	cp01, wrk01, wrk02
engine-image	3	cp01, wrk01, wrk02
instance-manager	3	cp01, wrk01, wrk02
longhorn-csi-plugin	3	cp01, wrk01, wrk02
csi-attacher	3	cp01, wrk01, wrk02
csi-provisioner	3	cp01, wrk01, wrk02
csi-resizer	3	cp01, wrk01, wrk02
csi-snapshotter	3	cp01, wrk01, wrk02
longhorn-ui	2	wrk01, wrk02
longhorn-driver-deployer	1	wrk02

Hinweis: longhorn-manager auf rnk-wrk01 zeigte initial einen CrashLoopBackOff (2 Restarts). Ursache war ein transientes Startproblem beim Instance Manager. Nach dessen Initialisierung lief der Pod stabil.

---

StorageClass

Longhorn registriert sich automatisch als Standard-StorageClass:

kubectl get storageclass

NAME                   PROVISIONER             RECLAIMPOLICY   VOLUMEBINDINGMODE      ALLOWVOLUMEEXPANSION
local-path (default)   rancher.io/local-path   Delete          WaitForFirstConsumer   false
longhorn (default)     driver.longhorn.io      Delete          Immediate              true
longhorn-static        driver.longhorn.io      Delete          Immediate              true

Da nun zwei Default-StorageClasses existieren, sollte local-path ggf. als nicht-default markiert werden:

kubectl patch storageclass local-path -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"false"}}}'

---

Services

longhorn-admission-webhook   ClusterIP   10.43.89.97    9502/TCP
longhorn-backend             ClusterIP   10.43.67.94    9500/TCP
longhorn-frontend            ClusterIP   10.43.107.228  80/TCP
longhorn-recovery-backend    ClusterIP   10.43.69.95    9503/TCP

Web-UI erreichbar machen (Port-Forward)

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

---

Helm Release Info

NAME     NAMESPACE       REVISION  STATUS    CHART           APP VERSION
longhorn longhorn-system 1         deployed  longhorn-1.11.1 v1.11.1

---

Nächste Schritte

• local-path als nicht-default StorageClass demarkieren → bereits korrekt (longhorn ist default)
• Longhorn-UI via Ingress dauerhaft exposieren → erledigt 2026-03-19
• Backup-Target konfigurieren (z.B. NFS oder S3-kompatibel)
• PVC-Test: Test-Deployment mit Longhorn-Volume erstellen

---

Longhorn-UI Ingress (2026-03-19)

Ingress für dauerhaften Zugriff auf die Longhorn-UI angelegt:

kubectl apply -f - <<EOF
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: longhorn-ingress
  namespace: longhorn-system
  annotations:
    traefik.ingress.kubernetes.io/router.entrypoints: web
spec:
  ingressClassName: traefik
  rules:
    - host: longhorn.192.168.11.180.nip.io
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: longhorn-frontend
                port:
                  number: 80
EOF

URL: http://longhorn.192.168.11.180.nip.io

Hinweis: Kein Passwortschutz — nur im internen Netz erreichbar.