Helm Upgrade Failed: Rollback und Reparatur-Anleitung

TL;DR

Ein fehlgeschlagenes Helm Upgrade hinterlässt das Release oft im Status failed oder pending-upgrade. Lösung: helm rollback <release> <revision> für ein sauberes Zurücksetzen, oder helm upgrade --force um einen erneuten Versuch zu erzwingen. Bei pending-upgrade hilft nur das manuelle Patchen des Secrets.

Die häufigste Ursache für ein fehlgeschlagenes helm upgrade: ein Timeout, weil neue Pods nicht ready werden.

# Aktuellen Release-Status prüfen
helm list -A

# History anzeigen -- zeigt alle Revisionen mit Status
helm history my-release -n production

Typische Ausgabe bei einem Problem:

REVISION  STATUS          DESCRIPTION
1         deployed        Install complete
2         failed          Upgrade "my-release" failed: timed out

Oder schlimmer:

REVISION  STATUS            DESCRIPTION
1         deployed          Install complete
2         pending-upgrade   Preparing upgrade

Die beiden Szenarien erfordern unterschiedliche Vorgehensweisen.

Szenario 1: Status "failed" -- Rollback durchführen

Ein Release im Status failed lässt sich sauber zurückrollen:

# Auf die letzte funktionierende Revision zurückrollen
helm rollback my-release 1 -n production

# Prüfen ob der Rollback erfolgreich war
helm list -n production
helm history my-release -n production

Nach dem Rollback sieht die History so aus:

REVISION  STATUS        DESCRIPTION
1         superseded    Install complete
2         failed        Upgrade "my-release" failed
3         deployed      Rollback to 1

Bevor Sie erneut upgraden, finden Sie zuerst die Ursache des Fehlers.

Ursachen für fehlgeschlagene Upgrades finden

# Helm gibt den Fehler im Status aus
helm status my-release -n production

# Pod-Status prüfen -- oft sind es nicht-startende Pods
kubectl get pods -n production -l app.kubernetes.io/instance=my-release

# Events im Namespace
kubectl get events -n production --sort-by='.lastTimestamp' | tail -20

Fehlermeldung	Ursache	Lösung
`timed out waiting for the condition`	Pods werden nicht ready	Readiness Probe, Image, Resources prüfen
`rendered manifests contain a resource that already exists`	Ressource existiert außerhalb von Helm	`kubectl annotate` mit Helm Ownership
`cannot patch ... field is immutable`	Immutable Field wird geändert	Resource löschen und neu erstellen lassen
`UPGRADE FAILED: another operation is in progress`	Paralleler Upgrade-Versuch	Warten oder pending-Status beheben

Szenario 2: Status "pending-upgrade" -- manuell reparieren

Das ist der unangenehme Fall. Ein Release im Status pending-upgrade oder pending-install blockiert jeden weiteren Helm-Befehl. Rollback funktioniert nicht, Upgrade auch nicht.

Helm speichert seinen State als Kubernetes Secrets. Sie müssen das letzte Secret manuell patchen:

# Helm-Secrets für das Release anzeigen
kubectl get secrets -n production -l owner=helm,name=my-release

# Das Secret mit der höchsten Revisionsnummer ist das problematische
# Beispiel: sh.helm.release.v1.my-release.v2

# Option A: Das pending Secret löschen (Helm fällt auf die vorherige Revision zurück)
kubectl delete secret sh.helm.release.v1.my-release.v2 -n production

# Danach funktioniert helm upgrade wieder
helm upgrade my-release ./my-chart -n production

Alternativ, wenn Sie keine Revision verlieren wollen:

# Option B: Secret-Status von pending-upgrade auf failed patchen
kubectl get secret sh.helm.release.v1.my-release.v2 -n production -o json \
  | jq '.data.release' -r | base64 -d | base64 -d | gzip -d \
  | jq '.info.status = "failed"' \
  | gzip | base64 | base64 \
  | xargs -I {} kubectl patch secret sh.helm.release.v1.my-release.v2 -n production \
    --type=merge -p '{"data":{"release":"{}"}}'

# Jetzt funktioniert helm rollback
helm rollback my-release 1 -n production

Immutable Fields: Der Spezialfall

Manche Kubernetes-Felder lassen sich nach der Erstellung nicht ändern. Das betrifft vor allem:

spec.selector bei Deployments
spec.clusterIP bei Services
spec.volumeName bei PVCs

Wenn Helm versucht, solche Felder zu ändern, schlägt das Upgrade fehl. Die pragmatische Lösung:

# Betroffene Ressource löschen (Helm erstellt sie beim nächsten Upgrade neu)
kubectl delete deployment my-app -n production

# Upgrade erneut versuchen
helm upgrade my-release ./my-chart -n production

Achtung: Das verursacht kurze Downtime. In Produktionsumgebungen sollten Sie eine Blue-Green-Strategie einsetzen.

Helm Upgrade absichern: Flags die helfen

Für zukünftige Upgrades nutzen Sie diese Flags:

# --atomic: Automatischer Rollback bei Fehler
helm upgrade my-release ./my-chart -n production --atomic

# --timeout: Mehr Zeit für große Deployments
helm upgrade my-release ./my-chart -n production --timeout 10m

# --dry-run: Vorab prüfen was passiert
helm upgrade my-release ./my-chart -n production --dry-run

# --force: Erzwingt Neustart aller Pods (delete + recreate statt patch)
helm upgrade my-release ./my-chart -n production --force

# Kombination für sichere Upgrades
helm upgrade my-release ./my-chart -n production \
  --atomic --timeout 10m --cleanup-on-fail

Das Flag --atomic ist besonders wertvoll: Es kombiniert --wait mit automatischem Rollback. Wenn das Upgrade fehlschlägt, steht Ihr altes Release automatisch wieder.

Helm History aufräumen

Bei vielen fehlgeschlagenen Versuchen wächst die History. Das kann zu Performance-Problemen führen:

# Maximale History-Einträge begrenzen (Default: 10)
helm upgrade my-release ./my-chart -n production --history-max 5

Debugging-Workflow für CI/CD Pipelines

In automatisierten Pipelines wollen Sie klare Fehlermeldungen:

#!/bin/bash
RELEASE="my-release"
NAMESPACE="production"
CHART="./my-chart"

# Status prüfen
STATUS=$(helm status "$RELEASE" -n "$NAMESPACE" -o json 2>/dev/null | jq -r '.info.status')

case "$STATUS" in
  "pending-upgrade"|"pending-install"|"pending-rollback")
    echo "Release stuck in $STATUS -- cleaning up"
    # Letztes Secret löschen
    LAST_SECRET=$(kubectl get secrets -n "$NAMESPACE" \
      -l "owner=helm,name=$RELEASE" \
      --sort-by='.metadata.creationTimestamp' -o name | tail -1)
    kubectl delete "$LAST_SECRET" -n "$NAMESPACE"
    ;;
  "failed")
    echo "Last upgrade failed -- rolling back"
    helm rollback "$RELEASE" 0 -n "$NAMESPACE"
    ;;
esac

# Upgrade mit Safety-Net
helm upgrade "$RELEASE" "$CHART" -n "$NAMESPACE" \
  --install --atomic --timeout 10m

FAQ

Was macht `helm rollback <release> 0`?

Die Revision 0 ist ein Sonderfall: Helm rollt auf die letzte als deployed markierte Revision zurück, ohne dass Sie die Nummer kennen müssen.

Kann ich ein Helm Release komplett löschen und neu installieren?

Ja, mit helm uninstall my-release -n production. Aber Achtung: PVCs werden standardmäßig nicht gelöscht (abhängig von der reclaim policy). Nutzen Sie --keep-history, wenn Sie die History behalten wollen.

Warum schlägt mein Upgrade mit "resource already exists" fehl?

Die Ressource wurde manuell oder von einem anderen Tool erstellt, nicht von Helm. Übernehmen Sie die Ownership mit kubectl annotate <resource> meta.helm.sh/release-name=my-release und kubectl annotate <resource> meta.helm.sh/release-namespace=production sowie kubectl label <resource> app.kubernetes.io/managed-by=Helm.

Wie verhindere ich pending-upgrade in der CI/CD Pipeline?

Nutzen Sie immer --atomic. Damit rollt Helm bei jedem Fehler automatisch zurück und hinterlässt kein Release im pending-Status.

Wenn Sie Helm-Deployments in Ihrer CI/CD Pipeline stabilisieren wollen oder Unterstützung bei komplexen Helm Chart-Strukturen brauchen, helfen wir gerne -- Kontakt aufnehmen.

Weiterführende Artikel:

Helm Upgrade Failed lösen: Rollback und Reparatur

Helm Upgrade Failed: Rollback und Reparatur-Anleitung

TL;DR

Szenario 1: Status "failed" -- Rollback durchführen

Ursachen für fehlgeschlagene Upgrades finden

Szenario 2: Status "pending-upgrade" -- manuell reparieren

Immutable Fields: Der Spezialfall

Helm Upgrade absichern: Flags die helfen

Helm History aufräumen

Debugging-Workflow für CI/CD Pipelines

FAQ

Was macht `helm rollback <release> 0`?

Kann ich ein Helm Release komplett löschen und neu installieren?

Warum schlägt mein Upgrade mit "resource already exists" fehl?

Wie verhindere ich pending-upgrade in der CI/CD Pipeline?

Kubernetes-Beratung gesucht?

📖 Verwandte Artikel

Helm Charts Tutorial: Eigene Charts erstellen und nutzen

Helm Charts für Anfänger: Eigenes Chart erstellen

Kubernetes Rollback: Blue-Green und Canary erklärt

ArgoCD ApplicationSets: Multi-App Deployment Patterns

Java Spring Boot auf Kubernetes containerisieren

Helm Upgrade Failed: Rollback und Reparatur-Anleitung

TL;DR

Szenario 1: Status "failed" -- Rollback durchführen

Ursachen für fehlgeschlagene Upgrades finden

Szenario 2: Status "pending-upgrade" -- manuell reparieren

Immutable Fields: Der Spezialfall

Helm Upgrade absichern: Flags die helfen

Helm History aufräumen

Debugging-Workflow für CI/CD Pipelines

FAQ

Was macht helm rollback <release> 0?

Kann ich ein Helm Release komplett löschen und neu installieren?

Warum schlägt mein Upgrade mit "resource already exists" fehl?

Wie verhindere ich pending-upgrade in der CI/CD Pipeline?

Kubernetes-Beratung gesucht?

📖 Verwandte Artikel

Helm Charts Tutorial: Eigene Charts erstellen und nutzen

Helm Charts für Anfänger: Eigenes Chart erstellen

Kubernetes Rollback: Blue-Green und Canary erklärt

ArgoCD ApplicationSets: Multi-App Deployment Patterns

Java Spring Boot auf Kubernetes containerisieren

Was macht `helm rollback <release> 0`?