Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 13: Sicher ausrollen – upgrade, warten, zurückrollen

Ziel: Upgrades so fahren, dass ein Fehler auffällt und rückgängig gemacht wird – und wissen, was Helm dabei speichert, was ein Rollback zurückdreht und was nicht. · Dauer: ca. 75 min · Voraussetzung: Tag 12

Briefing

  • helm upgrade --install ist idempotent: dieselbe Zeile für das erste und das hundertste Deployment.
  • Ohne --wait meldet Helm Erfolg, sobald die API die Objekte angenommen hat (Standard hookOnly: gewartet wird nur auf Hooks). --wait heißt watcher (kstatus); legacy ist das Verhalten von Helm 3.
  • --rollback-on-failure (früher --atomic) rollt ein gescheitertes Upgrade auf die letzte deployed-Revision zurück und schaltet --wait ein.
  • Ein Rollback stellt Manifeste wieder her – keine Daten, keine Schemas.
  • Helms Gedächtnis sind Secrets im Namespace des Releases, eines pro Revision.

Drill 1: Ein Befehl für install und upgrade

Die Experimente laufen mit dem kleinen Chart helper in tag13:

# auf prod
mkdir -p ~/helm/tag13 && cd ~/helm/charts
helm upgrade --install h ./helper -n tag13 --create-namespace | head -2
helm upgrade --install h ./helper -n tag13 | head -2

Erwartet:

Release "h" does not exist. Installing it now.
NAME: h
Release "h" has been upgraded. Happy Helming!
NAME: h

Dieselbe Zeile installiert beim ersten Mal und aktualisiert danach. Darum steht in Pipelines immer upgrade --install, nie install.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Kaputtes Image, ohne und mit Warten

# auf prod
time helm upgrade h ./helper -n tag13 --set image.tag=0.0.0-gibtsnicht | grep STATUS
sleep 8
kubectl -n tag13 get pods
time helm upgrade h ./helper -n tag13 --set image.tag=0.0.0-gibtsnicht \
  --wait --timeout 30s
helm history h -n tag13

Erwartet (gekürzt):

STATUS: deployed
real    0m1.227s
NAME                        READY   STATUS         RESTARTS   AGE
h-helper-5498ffdf68-vpm78   0/1     ErrImagePull   0          9s
h-helper-79c5cc98c4-4c75f   0/1     Running        0          11s
Error: UPGRADE FAILED: resource Deployment/tag13/h-helper not ready. status: InProgress,
message: Pending termination: 1
context deadline exceeded
real    0m31.067s
REVISION  UPDATED                   STATUS      CHART         ...  DESCRIPTION
1         Fri Nov 20 02:13:58 2026  superseded  helper-0.2.0  ...  Install complete
2         Fri Nov 20 02:13:59 2026  superseded  helper-0.2.0  ...  Upgrade complete
3         Fri Nov 20 02:14:00 2026  deployed    helper-0.2.0  ...  Upgrade complete
4         Fri Nov 20 02:14:10 2026  failed      helper-0.2.0  ...  Upgrade "h" failed: …

Ohne --wait ist Revision 3 nach einer Sekunde deployed – mit einem Image, das es nicht gibt. Mit --wait beobachtet Helm den Rollout und meldet nach 30 Sekunden failed. Merke dir Revision 3: Sie ist kaputt, gilt aber als letzte gute Revision.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Warte-Strategien und Jobs

# auf prod
cd ~/helm/tag13 && mkdir -p jobchart/templates
printf 'apiVersion: v2\nname: jobchart\nversion: 0.1.0\n' > jobchart/Chart.yaml
cat > jobchart/templates/job.yaml <<'EOF'
apiVersion: batch/v1
kind: Job
metadata:
  name: {{ .Release.Name }}-langsam
spec:
  template:
    spec:
      restartPolicy: Never
      containers:
        - name: schlafe
          image: curlimages/curl:8.23.0
          command: ["sleep", "15"]
EOF
for w in "" "--wait" "--wait --wait-for-jobs" "--wait=legacy" \
  "--wait=legacy --wait-for-jobs"; do
  s=$(date +%s); helm install j ./jobchart -n tag13 $w >/dev/null; e=$(date +%s)
  echo "$w: $((e-s)) s"; helm uninstall j -n tag13 >/dev/null
done
cd ~/helm/charts

Erwartet:

: 1 s
--wait: 1 s
--wait --wait-for-jobs: 20 s
--wait=legacy: 1 s
--wait=legacy --wait-for-jobs: 21 s
Aufruf Wartet auf Hinweis
ohne --wait nur Hooks (hookOnly) Standard
--wait Ressourcen bereit (watcher, kstatus) Jobs nur mit --wait-for-jobs
--wait=legacy Ressourcen bereit wie in Helm 3 Übergang
--timeout 5m Obergrenze je Operation Standard 5 Minuten

Fortschritt speichern? Kostenlos registrieren

Drill 4: Ohne readinessProbe nützt Warten nichts

helper lauscht auf 8080. Ein falscher Port ohne Probe:

# auf prod
helm install p ./helper -n tag13 --set port=9999 --set probePath=null \
  --wait --timeout 40s | grep STATUS
kubectl -n tag13 get pods -l app.kubernetes.io/instance=p
IP=$(kubectl -n tag13 get svc p-helper -o jsonpath='{.spec.clusterIP}')
curl -s -m 3 $IP/get || echo "curl exit $?"
helm upgrade p ./helper -n tag13 --set port=9999 --wait --timeout 30s 2>&1 | tail -2

Erwartet:

STATUS: deployed
NAME                        READY   STATUS    RESTARTS   AGE
p-helper-544459dc9f-24q4k   1/1     Running   0          2s
curl exit 7
Error: UPGRADE FAILED: resource Deployment/tag13/p-helper not ready. status: InProgress,
message: Pending termination: 1
context deadline exceeded

Ohne Probe ist der Pod „bereit“, sobald der Prozess läuft – --wait ist zufrieden, der Service liefert nichts. Mit Probe (/status/200 aus values.yaml) fällt der falsche Port auf. Helm ist nur so gut wie die Probes im Chart.

Fortschritt speichern? Kostenlos registrieren

Drill 5: Automatisch zurückrollen

Erst die Falle aus Drill 2:

# auf prod
helm upgrade h ./helper -n tag13 --set image.tag=0.0.0-gibtsnicht \
  --rollback-on-failure --timeout 30s 2>&1 \
  | grep -o 'an error occurred while rolling back'
helm history h -n tag13 --max 1 --show-rollback-revision
kubectl -n tag13 get deploy h-helper \
  -o jsonpath='{.spec.template.spec.containers[0].image}{"\n"}'

Erwartet (gekürzt):

an error occurred while rolling back
REVISION  UPDATED                   STATUS  CHART         ...  ROLLBACK  DESCRIPTION
6         Fri Nov 20 02:15:23 2026  failed  helper-0.2.0  ...  3         Release "h" f…
ghcr.io/mccutchen/go-httpbin:0.0.0-gibtsnicht

Der Rollback zielt auf Revision 3 – die letzte deployed-Revision, die ohne --wait kaputt durchgerutscht ist. Auch der Rollback scheitert. Lehre: --rollback-on-failure hilft nur, wenn jedes Deployment mit Warten lief. Mit einem sauberen Release:

# auf prod
helm uninstall h -n tag13
helm install r ./helper -n tag13 --wait | grep STATUS
time helm upgrade r ./helper -n tag13 --set image.tag=0.0.0-gibtsnicht \
  --rollback-on-failure --timeout 30s 2>&1 \
  | grep -o 'release r failed, and has been rolled back'
helm history r -n tag13 --show-rollback-revision
kubectl -n tag13 get deploy r-helper \
  -o jsonpath='{.spec.template.spec.containers[0].image}{"\n"}'

Erwartet (gekürzt):

release "h" uninstalled
STATUS: deployed
release r failed, and has been rolled back
real    0m31.651s
REVISION  UPDATED                   STATUS      ...  ROLLBACK  DESCRIPTION
1         Fri Nov 20 02:26:12 2026  superseded  ...            Install complete
2         Fri Nov 20 02:26:15 2026  failed      ...            Upgrade "r" failed: …
3         Fri Nov 20 02:26:46 2026  deployed    ...  1         Rollback to 1
ghcr.io/mccutchen/go-httpbin:2.26.0

Bei der Erstinstallation gibt es nichts zum Zurückrollen – Helm deinstalliert:

# auf prod
helm install h2 ./helper -n tag13 --set image.tag=0.0.0-gibtsnicht \
  --rollback-on-failure --timeout 20s 2>&1 | head -1
helm list -n tag13 -q
helm upgrade --install x ./helper -n default --atomic --dry-run=client 2>&1 | head -1

Erwartet:

Error: INSTALLATION FAILED: release h2 failed, and has been uninstalled due to
rollback-on-failure being set: resource Deployment/tag13/h2-helper not ready. …
p
r
Flag --atomic has been deprecated, use --rollback-on-failure instead

Laut helm upgrade --help setzt --rollback-on-failure --wait auf watcher – du musst es nicht zusätzlich angeben. --atomic funktioniert noch, warnt aber.

Fortschritt speichern? Kostenlos registrieren

Drill 6: Rollback, Beschreibung und Daten

Jetzt am echten Release notes. Erst eine Falle aus Tag 8:

# auf prod
helm upgrade notes ./notes -n notes -f values/prod.yaml --set env.NOTES_PAGE_SIZE=25 \
  2>&1 | grep 'at '
curl -s -H 'Host: api.notes.lab' -H 'X-API-Key: lab-key-123' localhost/notes \
  -d '{"text":"vor dem Rollback"}'; echo
helm rollback notes 26 -n notes --wait --description "Seitengröße zurück, Ticket LAB-13"

Erwartet (ID gekürzt):

- at '/env/NOTES_PAGE_SIZE': got number, want string
{"id":"1c0cdd92-…","text":"vor dem Rollback"}
Rollback was a success! Happy Helming!

--set macht aus 25 eine Zahl, das Schema will einen String – das Upgrade kam nie an. Der Rollback auf die laufende Revision 26 geht trotzdem durch und erzeugt Revision 27. Jetzt richtig, mit --set-string:

# auf prod
helm upgrade notes ./notes -n notes -f values/prod.yaml \
  --set-string env.NOTES_PAGE_SIZE=25 --wait | grep REVISION
kubectl -n notes get cm notes-config -o jsonpath='{.data.NOTES_PAGE_SIZE}{"\n"}'
sleep 5
curl -s -H 'Host: api.notes.lab' -H 'X-API-Key: lab-key-123' localhost/notes \
  -d '{"text":"in Revision 28"}'; echo
helm rollback notes -n notes --wait --description "Seitengröße zurück, Ticket LAB-13"
helm history notes -n notes --max 3 --show-rollback-revision
kubectl -n notes get cm notes-config -o jsonpath='{.data.NOTES_PAGE_SIZE}{"\n"}'
kubectl -n notes exec notes-postgres-0 -- \
  psql -U notes -tAc 'select text from notes order by created_at'
helm rollback notes 26 -n notes --description "$(printf 'x%.0s' {1..300})" 2>&1 \
  | tail -1

Erwartet (gekürzt):

REVISION: 28
25
{"id":"31f60edf-…","text":"in Revision 28"}
Rollback was a success! Happy Helming!
REVISION  ...  STATUS      CHART         ...  ROLLBACK  DESCRIPTION
27        ...  superseded  notes-0.11.0  ...  26        Seitengröße zurück, Ticket LAB-…
28        ...  superseded  notes-0.11.0  ...            Upgrade complete
29        ...  deployed    notes-0.11.0  ...  27        Seitengröße zurück, Ticket LAB-…
50
in Postgres
vor dem Rollback
in Revision 28
Error: description must be 256 characters or less, got 300

Ohne Nummer geht rollback eine Revision zurück. Neu in Helm 4.3: helm rollback --description (höchstens 256 Zeichen) und die Spalte ROLLBACK mit helm history --show-rollback-revision. Die Seitengröße ist zurück, die Notizen bleiben alle – ein Rollback fasst keine Daten an.

Fortschritt speichern? Kostenlos registrieren

Drill 7: Vorher schauen mit dem Server-Probelauf

# auf prod
helm upgrade notes ./notes -n notes -f values/prod.yaml \
  --set-string env.NOTES_PAGE_SIZE=30 --dry-run=server > ~/helm/tag13/plan.txt
grep -E '^(STATUS|REVISION|DESCRIPTION):' ~/helm/tag13/plan.txt
helm history notes -n notes --max 1 -o json | jq -r '.[0] | "\(.revision) \(.status)"'
helm get manifest notes -n notes > ~/helm/tag13/ist.yaml
sed -n '/^MANIFEST:/,/^NOTES:/p' ~/helm/tag13/plan.txt | sed '1d;$d' \
  > ~/helm/tag13/soll.yaml
diff ~/helm/tag13/ist.yaml ~/helm/tag13/soll.yaml

Erwartet (gekürzt):

STATUS: pending-upgrade
REVISION: 30
DESCRIPTION: Dry run complete
29 deployed
16c16
<   NOTES_PAGE_SIZE: "50"
---
>   NOTES_PAGE_SIZE: "30"
34c34
<   revision: "26"
---
>   revision: "30"
139c139
<         checksum/config: ec629186025b56c712177c25d2b3ab79f10f3766da7826dd4600b2…
---
>         checksum/config: 6811ba7dc65be8bb47031ad95e8dd1c4e2f06d81b549f5a834ecc1…

Der Probelauf rendert mit den echten Cluster-Fähigkeiten und lookup, speichert aber nichts – Revision 29 bleibt. Der Diff gegen helm get manifest zeigt genau die Änderung. Nebenbefund: In der ConfigMap steht revision: "26", obwohl Revision 29 läuft – ein Rollback stellt das gespeicherte Manifest wieder her, samt der damals gerenderten Revisionsnummer. Bequemer zeigt das Plugin helm-diff solche Unterschiede; Helm 4 prüft bei helm plugin install standardmäßig die Signatur (--verify, Standard true). Tag 14 installiert es mit Signaturprüfung.

Fortschritt speichern? Kostenlos registrieren

Drill 8: Wo Helm sich erinnert

# auf prod
kubectl -n notes get secrets -l owner=helm,name=notes \
  --sort-by=.metadata.creationTimestamp | tail -2
kubectl -n notes get secret sh.helm.release.v1.notes.v29 --show-labels | tail -1
kubectl -n notes get secret sh.helm.release.v1.notes.v29 -o jsonpath='{.data.release}' \
  | base64 -d | base64 -d | gzip -d | jq -r 'keys[]' | tr '\n' ' '; echo
kubectl -n notes get secret sh.helm.release.v1.notes.v29 -o jsonpath='{.data.release}' \
  | base64 -d | base64 -d | gzip -d | jq -c '.config.global, .info.status'
kubectl -n notes get secrets -l owner=helm,name=notes -o name | wc -l

Erwartet (gekürzt):

sh.helm.release.v1.notes.v28   helm.sh/release.v1   1      12m
sh.helm.release.v1.notes.v29   helm.sh/release.v1   1      11m
sh.helm.release.v1.notes.v29   helm.sh/release.v1   1   11m   modifiedAt=1795141165,
name=notes,owner=helm,status=deployed,version=29
apply_method chart config hooks info manifest name namespace version
{"dbSecret":"notes-db"}
"deployed"
10

Zweimal Base64 (einmal Helm, einmal Kubernetes), dann gzip. Darin stehen Chart, Werte (config), Manifest, Hooks und Status. Nur zehn Secrets: --history-max ist standardmäßig 10. Alles, was per --set kommt, ist für jeden mit Leserecht auf Secrets lesbar:

# auf prod
helm upgrade p ./helper -n tag13 --set dbPasswort=lab-geheim-123 --wait | grep REVISION
helm get values p -n tag13
kubectl -n tag13 get secret sh.helm.release.v1.p.v3 -o jsonpath='{.data.release}' \
  | base64 -d | base64 -d | gzip -d | grep -o 'lab-geheim-123' | head -1
HELM_DRIVER=configmap helm install d ./helper -n tag13 | grep STATUS
kubectl -n tag13 get configmap -l owner=helm
helm list -n tag13 -q
for i in 1 2 3; do
  HELM_DRIVER=configmap helm upgrade d ./helper -n tag13 --history-max 2 >/dev/null
done
kubectl -n tag13 get configmap -l owner=helm,name=d -o name
HELM_DRIVER=configmap helm uninstall d -n tag13

Erwartet:

REVISION: 3
USER-SUPPLIED VALUES:
dbPasswort: lab-geheim-123
lab-geheim-123
STATUS: deployed
NAME                      DATA   AGE
sh.helm.release.v1.d.v1   1      1s
p
r
configmap/sh.helm.release.v1.d.v3
configmap/sh.helm.release.v1.d.v4
release "d" uninstalled

Mit HELM_DRIVER=configmap liegt der Release in einer ConfigMap – und ist für ein normales helm list unsichtbar. Wer den Treiber wechselt, muss ihn überall setzen. --history-max 2 lässt nur die letzten zwei Revisionen stehen.

Status Bedeutung
deployed aktuelle, aktive Revision
superseded ältere, abgelöste Revision
failed gescheitert (Upgrade, Hook, Warten)
pending-install/-upgrade/-rollback Aktion läuft – oder hängt (Tag 19)
uninstalling, uninstalled wird entfernt bzw. mit --keep-history entfernt

Fortschritt speichern? Kostenlos registrieren

Übung: Speed-Drills

  1. Wie viele Release-Secrets hat notes? Zeitziel: 15 s
  2. Welches Secret gehört zur deployed-Revision? Nur per Label. Zeitziel: 20 s
  3. Lies die Beschreibung der letzten Revision von notes. Zeitziel: 20 s
  4. Auf welche Revision hat der letzte Rollback von r zurückgesetzt? Als JSON. Zeitziel: 30 s

Lösung

# auf prod
kubectl -n notes get secret -l owner=helm,name=notes -o name | wc -l
kubectl -n notes get secret -l owner=helm,name=notes,status=deployed -o name
helm history notes -n notes --max 1 -o json | jq -r '.[0].description'
helm history r -n tag13 -o json | jq -c '.[-1] | {revision, rollback_revision}'

Erwartet:

10
secret/sh.helm.release.v1.notes.v29
Seitengröße zurück, Ticket LAB-13
{"revision":3,"rollback_revision":1}

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

# auf prod
helm list -n notes --filter '^notes$'

Erwartet: Revision 29, notes-0.11.0, deployed.

# auf prod
helm test notes -n notes | grep Phase

Erwartet: Phase: Succeeded

# auf prod
curl -s -H 'Host: api.notes.lab' localhost/notes | jq length

Erwartet: 3

Challenge

Schreibe den Befehl, mit dem eine Pipeline r ausrollt: idempotent, wartend, mit Timeout 40 s, automatischem Rollback, höchstens drei gespeicherten Revisionen und einer Beschreibung mit dem Image-Tag. Fahre ihn dreimal: mit 2.26.0, mit einem kaputten Tag, wieder mit 2.26.0. Prüfe Historie und Release-Secrets.

Hinweis: Eine Schleife über drei Tags reicht, die Flags stehen alle in helm upgrade --help.

Lösung

# auf prod
for tag in 2.26.0 0.0.0-gibtsnicht 2.26.0; do
  helm upgrade --install r ./helper -n tag13 --set image.tag=$tag --wait --timeout 40s \
    --rollback-on-failure --history-max 3 --description "Deployment mit $tag" 2>&1 \
    | grep -E '^(STATUS|Error)' | cut -c1-80
done
helm history r -n tag13 --show-rollback-revision
kubectl -n tag13 get secret -l owner=helm,name=r -o name

Erwartet (gekürzt):

STATUS: deployed
Error: UPGRADE FAILED: release r failed, and has been rolled back due to rollbac
STATUS: deployed
REVISION  ...  STATUS      ...  ROLLBACK  DESCRIPTION
5         ...  failed      ...            Upgrade "r" failed: resource Deployment/…
6         ...  superseded  ...  4         Rollback to 4
7         ...  deployed    ...            Deployment mit 2.26.0
secret/sh.helm.release.v1.r.v5
secret/sh.helm.release.v1.r.v6
secret/sh.helm.release.v1.r.v7

Die Pipeline darf scheitern, der Cluster bleibt heil: Revision 6 ist der automatische Rollback, Revision 7 das nächste gute Deployment. Bei einem gescheiterten Upgrade überschreibt Helm deine Beschreibung mit der Fehlermeldung – auch das ist nützlich.

Fortschritt speichern? Kostenlos registrieren

Aufräumen

# auf prod
helm uninstall r p -n tag13
kubectl delete namespace tag13

Erwartet:

release "r" uninstalled
release "p" uninstalled
namespace "tag13" deleted

Am Chart hat sich heute nichts geändert, es gibt keinen Commit.

Interview-Notiz

  • Wie sieht ein sicheres Upgrade in Produktion aus? Feste Chart-Version, Werte aus Dateien im Git, vorher --dry-run=server oder Diff, dann upgrade --install mit --wait, Timeout und --rollback-on-failure, danach helm test und Monitoring.
  • Was stellt helm rollback wieder her, was nicht? Die gespeicherten Manifeste einer früheren Revision, als neue Revision. Keine Daten, keine PVC-Inhalte, kein Datenbank-Schema.
  • Wo speichert Helm seinen Zustand? In Secrets vom Typ helm.sh/release.v1 im Namespace des Releases, eines pro Revision – Chart, Werte, Manifest, Status, nur komprimiert, nicht verschlüsselt.

Enterprise-Notiz

  • Jedes Deployment mit Warten fahren, auch manuelle – sonst landet eine kaputte Revision als „letzte gute“ in der Historie, und der automatische Rollback trifft sie.
  • Leserechte auf Secrets im App-Namespace bedeuten Leserechte auf alle Werte aller Revisionen. RBAC entsprechend schneiden; Geheimnisse nie per --set.
  • --history-max bewusst setzen (5–10): genug für Rollbacks, klein genug für etcd. Ein Release-Secret darf höchstens 1 MiB groß sein.
  • Rollback-Beschreibungen mit Ticketnummer machen die Historie zum Änderungsprotokoll; Audit-Teams lesen helm history -o json.
  • Probes sind Teil der Auslieferungssicherheit: Ohne readinessProbe meldet --wait Erfolg für Dienste, die nichts beantworten.