StorageClass Migration

Dieses Runbook beschreibt die Migration eines Persistent Volumes von einer StorageClass zu einer anderen.

Unterstützte Verfahren:

  • Migration mittels CSI VolumeSnapshot

  • Migration mittels Velero Backup und Restore

Beispiel:

  • Quelle: linstor-r02

  • Ziel: linstor-local

Verfahren 1: Migration mittels VolumeSnapshot

Voraussetzungen

  • CSI Snapshots sind funktionsfähig

  • Die PVC verwendet eine VolumeSnapshotClass

  • Die Anwendung kann kurzzeitig heruntergefahren werden

  • Die StorageClass unterstützt die Wiederherstellung aus Snapshots

Übersicht

PVC
 |
 v
Snapshot
 |
 v
Scale Deployment/StatefulSet auf 0
 |
 v
PVC löschen
 |
 v
PVC aus Snapshot wiederherstellen
 |
 v
Scale Deployment/StatefulSet hoch

Beispiel

Anwendung:

Namespace: immich
PVC: library

Ziel:

linstor-r02 -> linstor-local

1. Snapshot erstellen

Snapshot anlegen:

apiVersion: snapshot.storage.k8s.io/v1
kind: VolumeSnapshot
metadata:
  name: library-migration
  namespace: immich
spec:
  volumeSnapshotClassName: linstor-snapshot1
  source:
    persistentVolumeClaimName: library

Anwenden:

kubectl apply -f snapshot.yaml

Status prüfen:

kubectl get volumesnapshot \
  -n immich \
  library-migration

Warten bis:

READYTOUSE=true

2. Anwendung stoppen

Für Deployments:

kubectl scale deployment immich-server \
  -n immich \
  --replicas=0

Für StatefulSets:

kubectl scale statefulset postgres \
  -n immich \
  --replicas=0

Prüfen:

kubectl get pods -n immich

Alle relevanten Pods müssen beendet sein.

3. PVC löschen

Wichtig:

Die PVC muss gelöscht werden.

Der Name der PVC wird später identisch wiederverwendet.

PVC prüfen:

kubectl get pvc \
  -n immich \
  library

PVC löschen:

kubectl delete pvc \
  -n immich \
  library

4. PVC aus Snapshot wiederherstellen

Die neue PVC muss exakt denselben Namen erhalten.

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: library
  namespace: immich
spec:
  storageClassName: linstor-local

  dataSource:
    name: library-migration
    kind: VolumeSnapshot
    apiGroup: snapshot.storage.k8s.io

  accessModes:
    - ReadWriteOnce

  resources:
    requests:
      storage: 100Gi

Anwenden:

kubectl apply -f pvc.yaml

Status prüfen:

kubectl get pvc \
  -n immich \
  library

Warten bis:

STATUS=Bound

5. Anwendung starten

Für Deployments:

kubectl scale deployment immich-server \
  -n immich \
  --replicas=1

Für StatefulSets:

kubectl scale statefulset postgres \
  -n immich \
  --replicas=1

6. Validierung

PVC prüfen:

kubectl get pvc \
  -n immich \
  library \
  -o wide

StorageClass prüfen:

kubectl get pvc \
  -n immich \
  library \
  -o jsonpath='{.spec.storageClassName}'

Erwartetes Ergebnis:

linstor-local

Pod prüfen:

kubectl get pods -n immich

Daten prüfen:

  • Anwendung startet erfolgreich

  • Datenbestand vollständig vorhanden

  • Keine Fehlermeldungen im Log

Aufräumen

Snapshot löschen:

kubectl delete volumesnapshot \
  -n immich \
  library-migration

Rollback

Falls die Migration fehlschlägt:

  1. Anwendung stoppen

  2. Wiederhergestellte PVC löschen

  3. Neue PVC mit ursprünglicher StorageClass erzeugen

  4. Wiederherstellung erneut aus dem Snapshot durchführen

  5. Anwendung starten

Da der Snapshot bis zum Abschluss der Migration erhalten bleibt, kann die Migration jederzeit erneut durchgeführt werden.

Verfahren 2: Migration mittels Velero

Diese Methode eignet sich besonders für die Migration mehrerer PVCs oder kompletter Anwendungen.

Velero kann während eines Restores die StorageClass automatisch umschreiben.

Voraussetzungen

  • Velero ist funktionsfähig

  • Backup Storage ist verfügbar

  • CSI Snapshots sind aktiviert

  • Die Anwendung kann kurzzeitig heruntergefahren werden

  • Resource Modifiers sind aktiviert

Übersicht

Deployment / StatefulSet
 |
 v
Velero Backup
 |
 v
Scale auf 0
 |
 v
PVC löschen
 |
 v
Velero Restore
 |
 v
StorageClass wird umgeschrieben
 |
 v
PVC wird mit gleichem Namen erstellt
 |
 v
Scale hoch

Beispiel

Ausgangssituation:

Namespace: immich
PVC: library

StorageClass:
linstor-r02

Ziel:

StorageClass:
linstor-local

1. Anwendung stoppen

Für Deployments:

kubectl scale deployment immich-server \
  -n immich \
  --replicas=0

Für StatefulSets:

kubectl scale statefulset postgres \
  -n immich \
  --replicas=0

Prüfen:

kubectl get pods -n immich

Alle relevanten Pods müssen beendet sein.

2. Velero Backup erstellen

Backup erzeugen:

velero backup create storageclass-migration \
  --include-namespaces immich \
  --wait

Backup prüfen:

velero backup get

Erwarteter Status:

Completed

3. Restore ConfigMap erstellen

Velero kann Ressourcen während des Restores verändern.

Beispiel:

apiVersion: v1
kind: ConfigMap
metadata:
  name: restore-item-action-config
  namespace: velero
data:
  config.yaml: |
    version: v1
    resourceModifierRules:
      - conditions:
          groupResource: persistentvolumeclaims
        patches:
          - operation: replace
            path: "/spec/storageClassName"
            value: "linstor-local"

Anwenden:

kubectl apply -f restore-configmap.yaml

4. Bestehende PVC löschen

PVC prüfen:

kubectl get pvc \
  -n immich \
  library

PVC löschen:

kubectl delete pvc \
  -n immich \
  library

Wichtig:

Die PVC wird während des Restores mit identischem Namen wiederhergestellt.

5. Restore durchführen

Restore starten:

velero restore create storageclass-migration \
  --from-backup storageclass-migration \
  --wait

Status prüfen:

velero restore get

Erwarteter Status:

Completed

6. Wiederhergestellte PVC prüfen

PVC prüfen:

kubectl get pvc \
  -n immich \
  library

StorageClass prüfen:

kubectl get pvc \
  -n immich \
  library \
  -o jsonpath='{.spec.storageClassName}'

Erwartetes Ergebnis:

linstor-local

Weiterhin prüfen:

kubectl get pvc \
  -n immich \
  library

Die PVC muss weiterhin den ursprünglichen Namen besitzen:

library

7. Anwendung starten

Für Deployments:

kubectl scale deployment immich-server \
  -n immich \
  --replicas=1

Für StatefulSets:

kubectl scale statefulset postgres \
  -n immich \
  --replicas=1

8. Validierung

Prüfen:

kubectl get pvc -n immich
kubectl get pods -n immich

Validierung:

  • PVC ist Bound

  • Neue StorageClass wird verwendet

  • Anwendung startet erfolgreich

  • Datenbestand vollständig vorhanden

  • Keine Fehlermeldungen im Log

Aufräumen

Restore löschen:

velero restore delete storageclass-migration

Backup löschen:

velero backup delete storageclass-migration

Restore Modifier entfernen:

kubectl delete configmap \
  -n velero \
  restore-item-action-config

Hinweise

  • Die PVC muss vor dem Restore gelöscht werden.

  • Der PVC-Name bleibt beim Restore unverändert.

  • Die StorageClass wird während des Restores umgeschrieben.

  • Die Methode eignet sich besonders für Migrationen mehrerer PVCs oder ganzer Anwendungen.

  • Das Verfahren sollte vor produktiven Migrationen in einer Testumgebung validiert werden.