Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 7: Piraeus als reiner CSI-Treiber

Ziel: Der Piraeus-Operator betreibt nur den CSI-Treiber, der mit dem LINSTOR auf den Hosts spricht. Du hast die drei Fallen dieses Aufbaus selbst ausgelöst und gelöst. · Dauer: ca. 60 min · Voraussetzung: Tag 6

Briefing

  • Der Piraeus-Operator kann alles: Controller, Satellites, DRBD-Modul, CSI. Hier soll er nur den CSI-Treiber liefern. LINSTOR läuft auf den Hosts und ist über die VIP erreichbar.
  • Die Ressource LinstorCluster beschreibt, was der Operator betreibt. Das Chart linstor-cluster erzeugt sie aus Helm-Werten.
  • Die Werte entstehen heute in drei Runden, jede Runde deckt eine Falle auf.
  • Versionen: Operator v2.12.1 bringt CSI v1.13.2 mit, und der verlangt LINSTOR 1.35. Gegen LINSTOR 1.34.2 läuft CSI v1.12.0 – das Image wird gepinnt.

Drill 1: helm auf dem Arbeitsplatz

# auf k0s-ctrl
mkdir -p ~/k0s-lab/tag07 && cd ~/k0s-lab/tag07
ARCH=$(dpkg --print-architecture); V=v4.3.2
curl -sSfLO https://get.helm.sh/helm-$V-linux-$ARCH.tar.gz
curl -sSfLO https://get.helm.sh/helm-$V-linux-$ARCH.tar.gz.sha256sum
sha256sum -c helm-$V-linux-$ARCH.tar.gz.sha256sum
tar xzf helm-$V-linux-$ARCH.tar.gz
sudo install -m 755 linux-$ARCH/helm /usr/local/bin/helm
helm version

Erwartet (gekürzt):

helm-v4.3.2-linux-amd64.tar.gz: OK
version.BuildInfo{Version:"v4.3.2", GitCommit:"8346aaa5...", GitTreeState:"clean", ...}

Fortschritt speichern? Kostenlos registrieren

Drill 2: Den Operator installieren

Das Chart des Operators liegt im Git-Repository des Projekts. Seine Version ist die Operator-Version:

# auf k0s-ctrl
git clone -q --depth 1 --branch v2.12.1 \
  https://github.com/piraeusdatastore/piraeus-operator.git
helm install piraeus-operator piraeus-operator/charts/piraeus \
  --namespace piraeus-datastore --create-namespace --set installCRDs=true
kubectl -n piraeus-datastore rollout status deploy/piraeus-operator-controller-manager
kubectl -n piraeus-datastore get cm piraeus-operator-image-config -o yaml \
  | grep -A2 'linstor-csi:'

Erwartet (gekürzt):

STATUS: deployed
...
deployment "piraeus-operator-controller-manager" successfully rolled out
      linstor-csi:
        tag: v1.13.2
        image: piraeus-csi

installCRDs=true ist Pflicht, die Vorgabe false installiert den Operator ohne seine Ressourcentypen. Die Image-Konfiguration zeigt: Ohne Eingriff käme CSI v1.13.2.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Runde 1 – externer Controller, keine Satellites

Komponente Hier Warum
Controller, Satellites aus laufen auf den Hosts
CSI-Controller, CSI-Node an PVC → LINSTOR, Volumes mounten
HA-Controller, Affinity-Controller aus bewusst nicht genutzt
NFS-Server aus kein ReadWriteMany
# auf k0s-ctrl
cat > werte-1.yaml <<'EOF'
linstorCluster:
  externalController:
    url: http://10.10.0.100:3370
  nodeSelector:
    piraeus.io/managed-satellite: "true"
  highAvailabilityController:
    enabled: false
  affinityController:
    enabled: false
  nfsServer:
    enabled: false
  csiController:
    podTemplate:
      spec:
        containers:
          - name: linstor-csi
            image: quay.io/piraeusdatastore/piraeus-csi:v1.12.0
  csiNode:
    podTemplate:
      spec:
        containers:
          - name: linstor-csi
            image: quay.io/piraeusdatastore/piraeus-csi:v1.12.0
EOF
helm repo add piraeus-charts https://piraeus.io/helm-charts/
helm repo update
helm install linstor-cluster piraeus-charts/linstor-cluster --version 1.3.2 \
  -n piraeus-datastore -f werte-1.yaml
J='{range .items[].status.conditions[*]}{.type}={.status} {.message}{"\n"}{end}'
kubectl get linstorcluster -o jsonpath="$J"
kubectl -n piraeus-datastore get pods

Erwartet (gekürzt):

Applied=True Resources applied
Available=True Controller 1.34.2 (API: 1.28.0, Git: 92d55e45...) reachable at 'h...
Configured=True Properties applied
NAME                                                   READY   STATUS    RESTARTS   AGE
linstor-csi-controller-6468c4bcbb-p9wb4                0/6     Pending   0          60s
piraeus-operator-controller-manager-77f676b49d-gbrhd   1/1     Running   0          104s

Die VIP ist erreichbar, der Controller meldet 1.34.2 mit REST-API 1.28.0. Der nodeSelector nennt ein Label, das kein Node trägt – so startet der Operator keine Satellites. Aber der CSI-Controller hängt, und CSI-Node-Pods gibt es gar keine:

# auf k0s-ctrl
kubectl -n piraeus-datastore describe pod \
  -l app.kubernetes.io/component=linstor-csi-controller | tail -1 | cut -c1-88
kubectl -n piraeus-datastore get ds linstor-csi-node \
  -o custom-columns=DESIRED:.status.desiredNumberScheduled,\
SELECTOR:.spec.template.spec.nodeSelector

Erwartet (gekürzt):

  Warning  FailedScheduling  68s   default-scheduler  0/3 nodes are available: 3 no
DESIRED   SELECTOR
0         map[piraeus.io/managed-satellite:true]

Falle 1: Der nodeSelector gilt nicht nur für Satellites, sondern für alle Pods des Operators, auch die CSI-Pods. Die podTemplate wird als Strategic-Merge-Patch angewendet – darin löscht null einen Schlüssel wieder.

Fortschritt speichern? Kostenlos registrieren

Drill 4: Runde 2 – der kubelet-Pfad von k0s

Ergänze in csiController und csiNode unter podTemplate.spec jeweils:

        nodeSelector:
          piraeus.io/managed-satellite: null

Speichere das als werte-2.yaml und spiele es ein:

# auf k0s-ctrl
diff werte-1.yaml werte-2.yaml
helm upgrade linstor-cluster piraeus-charts/linstor-cluster --version 1.3.2 \
  -n piraeus-datastore -f werte-2.yaml
kubectl -n piraeus-datastore get pods

Erwartet (gekürzt):

14a15,16
>         nodeSelector:
>           piraeus.io/managed-satellite: null
20a23,24
>         nodeSelector:
>           piraeus.io/managed-satellite: null
...
NAME                                                   READY   STATUS     RESTARTS   AGE
linstor-csi-controller-7f7f5f4596-6m6nm                6/6     Running    0          90s
linstor-csi-node-hwtcc                                 0/3     Init:0/1   0          89s
linstor-csi-node-pxcll                                 0/3     Init:0/1   0          89s
linstor-csi-node-wf8zf                                 0/3     Init:0/1   0          89s

Der CSI-Controller v1.12.0 läuft gegen LINSTOR 1.34.2. Die Node-Pods hängen:

# auf k0s-ctrl
kubectl -n piraeus-datastore get events --field-selector reason=FailedMount \
  | tail -1 | cut -c1-88
kubectl -n piraeus-datastore get events --field-selector reason=FailedMount \
  -o jsonpath='{.items[-1:].message}{"\n"}' | fold -w 88

Erwartet (gekürzt):

42s   Warning   FailedMount   pod/linstor-csi-node-hwtcc   MountVolume.SetUp failed fo
MountVolume.SetUp failed for volume "registration-dir" : hostPath type check failed: /va
r/lib/kubelet/plugins_registry is not a directory

Falle 2: k0s legt das kubelet unter /var/lib/k0s/kubelet ab (Tag 2), der Treiber sucht /var/lib/kubelet. Drei Host-Pfade, ein zusätzlicher Mount mit gleichem Pfad im Container und der Registrierungspfad müssen umgebogen werden. Ergänze in csiNode:

          - name: linstor-csi
            image: quay.io/piraeusdatastore/piraeus-csi:v1.12.0
            volumeMounts:
              - name: publish-dir
                mountPath: /var/lib/k0s/kubelet
                mountPropagation: Bidirectional
          - name: csi-node-driver-registrar
            env:
              - name: KUBELET_REGISTRATION_PATH
                value: /var/lib/k0s/kubelet/plugins/linstor.csi.linbit.com/csi.sock
        volumes:
          - name: publish-dir
            hostPath:
              path: /var/lib/k0s/kubelet
          - name: registration-dir
            hostPath:
              path: /var/lib/k0s/kubelet/plugins_registry
          - name: plugin-dir
            hostPath:
              path: /var/lib/k0s/kubelet/plugins/linstor.csi.linbit.com

Das kubelet übergibt dem Treiber absolute Pfade unter /var/lib/k0s/kubelet. Die müssen im Container genauso existieren, deshalb derselbe Pfad innen wie außen.

Fortschritt speichern? Kostenlos registrieren

Drill 5: Runde 3 – die Neustart-Schleife

Der vollständige Stand als werte-3.yaml – diese Datei gilt für alle weiteren Tage:

# auf k0s-ctrl
cat > werte-3.yaml <<'EOF'
linstorCluster:
  externalController:
    url: http://10.10.0.100:3370
  nodeSelector:
    piraeus.io/managed-satellite: "true"
  highAvailabilityController:
    enabled: false
  affinityController:
    enabled: false
  nfsServer:
    enabled: false
  csiController:
    podTemplate:
      spec:
        nodeSelector:
          piraeus.io/managed-satellite: null
        containers:
          - name: linstor-csi
            image: quay.io/piraeusdatastore/piraeus-csi:v1.12.0
  csiNode:
    podTemplate:
      spec:
        nodeSelector:
          piraeus.io/managed-satellite: null
        containers:
          - name: linstor-csi
            image: quay.io/piraeusdatastore/piraeus-csi:v1.12.0
            volumeMounts:
              - name: publish-dir
                mountPath: /var/lib/k0s/kubelet
                mountPropagation: Bidirectional
          - name: csi-node-driver-registrar
            env:
              - name: KUBELET_REGISTRATION_PATH
                value: /var/lib/k0s/kubelet/plugins/linstor.csi.linbit.com/csi.sock
        volumes:
          - name: publish-dir
            hostPath:
              path: /var/lib/k0s/kubelet
          - name: registration-dir
            hostPath:
              path: /var/lib/k0s/kubelet/plugins_registry
          - name: plugin-dir
            hostPath:
              path: /var/lib/k0s/kubelet/plugins/linstor.csi.linbit.com
EOF
helm upgrade linstor-cluster piraeus-charts/linstor-cluster --version 1.3.2 \
  -n piraeus-datastore -f werte-3.yaml
sleep 50
kubectl -n piraeus-datastore get pods -l app.kubernetes.io/component=linstor-csi-node
kubectl get csinodes \
  -o 'custom-columns=NODE:.metadata.name,DRIVERS:.spec.drivers[*].name'

Erwartet:

NAME                     READY   STATUS            RESTARTS   AGE
linstor-csi-node-6x289   3/3     Running           0          53s
linstor-csi-node-cpt8x   0/3     PodInitializing   0          53s
linstor-csi-node-pbxrz   3/3     Running           0          3s
NODE     DRIVERS
k0s-w1   <none>
k0s-w2   linstor.csi.linbit.com
k0s-w3   <none>

Die Pods laufen, aber nie lange – AGE 3s. Keine Abstürze, keine Fehler in den Logs:

# auf k0s-ctrl
kubectl -n piraeus-datastore get events --sort-by=.lastTimestamp \
  | grep Killing | tail -2 | cut -c1-88

Erwartet:

1s          Normal    Killing             pod/linstor-csi-node-fhdxf
1s          Normal    Killing             pod/linstor-csi-node-fhdxf

Falle 3: Der Operator vergleicht für jeden CSI-Node die Topologie-Schlüssel, die der Treiber an Kubernetes meldet (linbit.com/hostname), mit den Eigenschaften Aux/topology/* des LINSTOR-Nodes. Weichen sie ab, löscht er den Pod, damit der Treiber sich neu registriert. Bei eigenen Satellites setzt er die Eigenschaft selbst – unsere Nodes verwaltet er nicht.

# auf k0s-ctrl
linstor node set-property k0s-w1 Aux/topology/linbit.com/hostname k0s-w1
linstor node set-property k0s-w2 Aux/topology/linbit.com/hostname k0s-w2
linstor node set-property k0s-w3 Aux/topology/linbit.com/hostname k0s-w3
sleep 120
kubectl -n piraeus-datastore get pods -l app.kubernetes.io/component=linstor-csi-node
C='NODE:.metadata.name,DRIVERS:.spec.drivers[*].name'
kubectl get csinodes -o "custom-columns=$C,KEYS:.spec.drivers[*].topologyKeys"

Erwartet (gekürzt):

NAME                     READY   STATUS    RESTARTS   AGE
linstor-csi-node-b5rtx   3/3     Running   0          118s
linstor-csi-node-ph9sq   3/3     Running   0          118s
linstor-csi-node-swqm6   3/3     Running   0          119s
NODE     DRIVERS                  KEYS
k0s-w1   linstor.csi.linbit.com   [linbit.com/hostname]
k0s-w2   linstor.csi.linbit.com   [linbit.com/hostname]
k0s-w3   linstor.csi.linbit.com   [linbit.com/hostname]

Die Witness bekommt keinen Eintrag, auf ihr läuft kein CSI-Node. Ein neuer Worker ohne diese Eigenschaft bringt die Schleife zurück – nur auf diesem einen Node. Sie gehört deshalb in das Runbook oder Playbook, mit dem du Nodes in LINSTOR registrierst – die Rollen aus Tag 16 lassen diesen Schritt bewusst aus.

Fortschritt speichern? Kostenlos registrieren

Drill 6: Was der Operator am Controller ändert

Configured=True Properties applied ist wörtlich gemeint:

# auf k0s-ctrl
linstor --no-utf8 --no-color controller list-properties \
  | grep -E 'piraeus|AutoEvict|Net/rr|Resource/on' | cut -c1-88

Erwartet (gekürzt):

| Aux/piraeus.io/last-applied                        | ["Aux/piraeus.io/managed-by","Drb
| Aux/piraeus.io/managed-by                          | piraeus-operator
| DrbdOptions/AutoEvictAllowEviction                 | false
| DrbdOptions/Net/rr-conflict                        | retry-connect
| DrbdOptions/Resource/on-no-data-accessible         | suspend-io
| DrbdOptions/Resource/on-no-quorum                  | suspend-io
| DrbdOptions/Resource/on-suspended-primary-outdated | force-secondary

Diese Werte gelten auf Controller-Ebene für alle Ressourcen, auch außerhalb von Kubernetes. Was spezifischer gesetzt ist (Resource-Group, Ressource), gewinnt – linstor_db behält ihr io-error:

# auf k0s-w1
sudo drbdsetup show linstor_db | sed -n '/options/,/}/p'

Erwartet:

    options {
        auto-promote        no;
        quorum              majority;
        on-no-quorum        io-error;
        on-suspended-primary-outdated   force-secondary;
    }

AutoEvictAllowEviction=false schaltet die automatische Evakuierung ausgefallener Nodes ab – wichtig für Tag 10. Was du von Hand änderst, setzt der Operator zurück:

# auf k0s-ctrl
date +%T
linstor controller set-property DrbdOptions/AutoEvictAllowEviction true
sleep 90
linstor --no-utf8 --no-color controller list-properties \
  | grep 'AutoEvictAllowEviction ' | cut -c1-75

Erwartet (gekürzt):

01:11:46
SUCCESS:
...
| DrbdOptions/AutoEvictAllowEviction                 | false

Im Labor war der Wert nach gut einer Minute wieder false.

Fortschritt speichern? Kostenlos registrieren

Drill 7: Warum CSI v1.12.0?

Was passiert mit dem Standard-Image, zeigt ein kurzer Versuch. Er bricht den Treiber für zwei Minuten, Volumes gibt es noch keine:

# auf k0s-ctrl
sed 's/piraeus-csi:v1.12.0/piraeus-csi:v1.13.2/' werte-3.yaml > werte-1132.yaml
helm upgrade linstor-cluster piraeus-charts/linstor-cluster --version 1.3.2 \
  -n piraeus-datastore -f werte-1132.yaml
sleep 75
kubectl -n piraeus-datastore get pods | grep csi
kubectl -n piraeus-datastore logs deploy/linstor-csi-controller -c linstor-csi \
  --tail=1 | fold -w 88

Erwartet (gekürzt):

linstor-csi-controller-6ffc6864f5-ns29z    5/6     CrashLoopBackOff   9 (13s ago)   75s
linstor-csi-node-5crjs                     2/3     CrashLoopBackOff   5 (9s ago)    69s
...
time="2026-11-20T01:11:08Z" level=fatal msg="LINSTOR 1.34.2 (REST API 1.28.0) is not sup
ported: the driver requires REST API 1.29 or newer in the 1.x series, shipped with LINST
OR 1.35"

Die Meldung ist eindeutig. Zurück auf den gepinnten Stand:

# auf k0s-ctrl
helm upgrade linstor-cluster piraeus-charts/linstor-cluster --version 1.3.2 \
  -n piraeus-datastore -f werte-3.yaml
kubectl -n piraeus-datastore rollout status ds/linstor-csi-node
rm werte-1132.yaml

Erwartet (gekürzt):

daemon set "linstor-csi-node" successfully rolled out

Genau diese Kopplung bestimmt an Tag 15 die Reihenfolge: erst LINSTOR auf 1.35, dann CSI.

Fortschritt speichern? Kostenlos registrieren

Übung: Speed-Drills

  1. Zeig, welche LINSTOR-Version der Operator am externen Controller sieht. Zeitziel: 20 s
  2. Zeig das CSI-Image aller Pods im Namespace piraeus-datastore. Zeitziel: 30 s
  3. Zeig, welche Nodes den CSI-Treiber registriert haben. Zeitziel: 15 s
  4. Zeig, welche Controller-Eigenschaften vom Operator stammen. Zeitziel: 30 s

Lösung

# auf k0s-ctrl
kubectl get linstorcluster -o \
  jsonpath='{.items[0].status.conditions[?(@.type=="Available")].message}{"\n"}'
kubectl -n piraeus-datastore get pods \
  -o jsonpath='{range .items[*]}{.metadata.name} {.spec.containers[0].image}{"\n"}{end}'
kubectl get csinodes \
  -o 'custom-columns=NODE:.metadata.name,DRIVERS:.spec.drivers[*].name'
curl -s http://172.16.0.186:3370/v1/controller/properties \
  | python3 -c 'import json,sys; d=json.load(sys.stdin)
print(d["Aux/piraeus.io/last-applied"])'

Erwartet (gekürzt):

Controller 1.34.2 (API: 1.28.0, Git: 92d55e45...) reachable at 'http://10.10.0.100:3370'
linstor-csi-controller-7f7f5f4596-ddqlj quay.io/piraeusdatastore/piraeus-csi:v1.12.0
linstor-csi-node-7hgts quay.io/piraeusdatastore/piraeus-csi:v1.12.0
...
piraeus-operator-controller-manager-77f676b49d-gbrhd quay.io/piraeusdatastore/pirae...
...
["Aux/piraeus.io/managed-by","DrbdOptions/AutoEvictAllowEviction","DrbdOptions/Net/...

curl nimmt die Management-IP eines Kandidaten. Läuft der Controller gerade woanders, probiere die nächste.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

# auf k0s-ctrl
helm -n piraeus-datastore get values linstor-cluster | grep -c 'piraeus-csi:v1.12.0'

Erwartet: 2 – Helm hat die Werte aus werte-3.yaml, nicht die aus dem Versuch mit v1.13.2.

# auf k0s-ctrl
kubectl -n piraeus-datastore get pods

Erwartet: linstor-csi-controller 6/6, drei linstor-csi-node 3/3, Operator 1/1, alle Running und älter als zwei Minuten.

# auf k0s-ctrl
kubectl get csinodes \
  -o 'custom-columns=NODE:.metadata.name,DRIVERS:.spec.drivers[*].name'

Erwartet: linstor.csi.linbit.com auf k0s-w1, k0s-w2 und k0s-w3.

# auf k0s-ctrl
linstor --no-utf8 --no-color node list-properties k0s-w3

Erwartet: Aux/topology/linbit.com/hostname | k0s-w3 neben Aux/zone | a.

Challenge

Dein Team will die automatische Evakuierung ausgefallener Nodes doch einschalten (DrbdOptions/AutoEvictAllowEviction=true). Von Hand gesetzt hält der Wert keine zwei Minuten. Setze ihn dauerhaft, prüfe das nach zwei Minuten, und stell danach den Buch-Stand (false) wieder her.

Hinweis: Die CRD LinstorCluster hat ein Feld für Eigenschaften auf Cluster-Ebene (kubectl explain linstorcluster.spec.properties).

Lösung

Kopiere werte-3.yaml nach werte-challenge.yaml und ergänze unter linstorCluster::

  properties:
    - name: DrbdOptions/AutoEvictAllowEviction
      value: "true"
# auf k0s-ctrl
helm upgrade linstor-cluster piraeus-charts/linstor-cluster --version 1.3.2 \
  -n piraeus-datastore -f werte-challenge.yaml
sleep 120
linstor --no-utf8 --no-color controller list-properties \
  | grep 'AutoEvictAllowEviction ' | cut -c1-75
helm upgrade linstor-cluster piraeus-charts/linstor-cluster --version 1.3.2 \
  -n piraeus-datastore -f werte-3.yaml
sleep 20
linstor --no-utf8 --no-color controller list-properties \
  | grep 'AutoEvictAllowEviction ' | cut -c1-75
rm werte-challenge.yaml

Erwartet (gekürzt):

| DrbdOptions/AutoEvictAllowEviction                 | true
...
| DrbdOptions/AutoEvictAllowEviction                 | false

Einstellungen am Controller, die der Operator kennt, gehören in die Helm-Werte. Sonst gewinnt beim nächsten Abgleich der Operator.

Fortschritt speichern? Kostenlos registrieren

Interview-Notiz

  • Warum Piraeus nur als CSI-Treiber? LINSTOR auf den Hosts ist unabhängig von Kubernetes-Updates und Operator-Fehlern. Der Operator liefert nur das Bindeglied.
  • Was ist auf k0s anders? Der kubelet-Pfad /var/lib/k0s/kubelet. Jeder CSI-Treiber braucht dort seine Pfade.
  • CSI-Pods starten ständig neu, ohne Fehler – woran denkst du? An fehlende Aux/topology/*-Eigenschaften auf fremd verwalteten LINSTOR-Nodes.

Enterprise-Notiz

  • Image-Versionen immer pinnen und mit der LINSTOR-Version zusammen freigeben; die Kompatibilität steht im Changelog von linstor-csi.
  • Images aus einer internen Registry spiegeln; der Operator nimmt dafür die image-config bzw. eigene Image-Pfade in den Helm-Werten.
  • REST-API des Controllers mit TLS und Client-Zertifikat absichern, wenn das Storage-Netz nicht exklusiv ist (linstorCluster.apiTLS bzw. eigene Secrets für den externen Controller).
  • Helm-Werte in Git, Upgrades per GitOps (Argo CD, Flux) – ein händisches helm upgrade mit falscher Datei setzt sonst alle drei Korrekturen zurück.