Das Deployment ist fertig. Der Container startet trotzdem nicht.

ImagePullBackOff systematisch untersuchen

ImagePullBackOff systematisch untersuchen

Lesezeit: ca. 5–6 Minuten

Die Pipeline ist grün. Das Manifest wurde erfolgreich an Kubernetes übergeben. Im Deployment steht das neue Image. Doch der Container startet nicht. Statt Anwendungslogs erscheint in der Pod-Übersicht ImagePullBackOff. Ein erneuter Rollout ändert nichts. Auch das Löschen des Pods führt nur dazu, dass sein Nachfolger denselben Fehler zeigt.

In dieser Situation liegt das Problem vor dem eigentlichen Anwendungsstart. Der Node kann das benötigte Container-Image nicht erfolgreich beziehen. Die Anwendung selbst hat möglicherweise noch keine einzige Zeile Code ausgeführt. Wer jetzt ausschließlich im Quellcode oder in der Applikationskonfiguration sucht, untersucht die falsche Phase.

Erfolgreich eingereicht ist nicht erfolgreich gestartet

Eine Pipeline kann mehrere unterschiedliche Erfolgskriterien haben. Der Build erzeugt ein Image. Der Push überträgt es in eine Registry. Anschließend wird ein Kubernetes-Objekt erstellt oder geändert. Keiner dieser einzelnen Schritte beweist für sich, dass ein produktiver Node das Image herunterladen und ausführen kann.

Die offizielle Kubernetes-Dokumentation beschreibt ImagePullBackOff als Zustand nach einem fehlgeschlagenen Image-Bezug. Kubernetes versucht den Download erneut und vergrößert dabei die Wartezeit. Die Bezeichnung erklärt damit das Wiederholungsverhalten, aber noch nicht die Ursache.

Für eine belastbare Release-Pipeline muss deshalb klar sein, ob sie lediglich die API-Änderung bestätigt oder auch auf betriebsbereite Pods wartet. Ein grüner Schritt namens „Deploy“ sollte nicht mehr versprechen, als er tatsächlich überprüft.

Die erste wichtige Information steht im Event

Der Einstieg ist die Beschreibung des betroffenen Pods. Die Events nennen häufig deutlich präzisere Fehler als die kompakte Statusspalte: etwa einen nicht gefundenen Manifest-Verweis, eine fehlgeschlagene Authentifizierung, einen Timeout oder einen Fehler bei der Zertifikatsprüfung.

Ein lesender Diagnoseaufruf ist beispielsweise:

kubectl describe pod <pod-name> -n <namespace>

Dabei sollten der genaue Image-Verweis, der zugewiesene Node und die vollständige Fehlermeldung festgehalten werden. Zugangsdaten aus Secrets gehören dagegen nicht in Tickets oder gemeinsam genutzte Diagnoseausgaben.

Die Abgrenzung zu CrashLoopBackOff ist wichtig. Dort hat ein Container typischerweise bereits gestartet und beendet sich wiederholt. Bei einem Image-Pull-Fehler kann die Suche nach Anwendungslogs ins Leere laufen, weil es noch keinen entsprechenden Prozess gab.

Existiert genau dieses Image?

Zuerst wird der vollständige Verweis geprüft: Registry-Hostname, Repository-Pfad, Tag oder Digest. Ein Build kann erfolgreich gewesen sein, während das Manifest auf einen anders geschriebenen Tag zeigt. Ebenso kann ein Release-Tag bereits im Repository existieren, aber nicht in der Registry, aus der die Produktion lädt.

Ein illustratives Beispiel: Die Pipeline baut release-2026-11, das Deployment verwendet jedoch release_2026_11. Der Unterschied ist klein, die Auswirkung eindeutig. Wiederholungsversuche können ein nicht vorhandenes Image nicht herstellen.

Eine weitere Fehlerquelle sind Aufbewahrungsregeln. Wenn ein weiterhin referenziertes Image aus der Registry entfernt wurde, können bestehende Pods zunächst weiterlaufen. Erst ein neuer Node oder ein Neustart ohne passenden lokalen Cache macht die fehlende Verfügbarkeit sichtbar. Die Wiederanlauffähigkeit hängt damit auch an der Retention der Artefakte.

Die Berechtigung des Nodes ist entscheidend

Dass ein Entwickler das Image auf seinem Notebook ziehen kann, beweist nicht, dass Kubernetes dieselben Rechte hat. Lokale Logins, Service Accounts und Image-Pull-Secrets sind unterschiedliche Zugriffskontexte.

Bei privaten Registries muss geprüft werden, ob das referenzierte Secret im richtigen Namespace vorhanden ist, korrekt zugeordnet wurde und für genau diese Registry gilt. Auch der Service Account des Pods kann eine Rolle spielen. Eine Secret-Rotation, die nur einen Teil der Namespaces erreicht, erzeugt entsprechend uneinheitliche Fehler.

Die Diagnose sollte deshalb die tatsächliche Pod-Spezifikation betrachten. Eine korrekt aussehende Helm-Values-Datei reicht nicht, wenn beim Rendern oder durch zusätzliche Mechanismen eine andere Konfiguration im Cluster angekommen ist.

Den Netzwerkpfad vom Node aus bewerten

Der Image-Download wird durch die Container-Runtime auf dem Node ausgeführt. Der relevante Netzwerkpfad muss deshalb aus dieser Perspektive funktionieren. Ein erfolgreicher Request aus einem bestehenden Anwendungs-Pod ist ein nützlicher Hinweis, aber kein vollständiger Beweis.

Zu prüfen sind DNS-Auflösung, Routing, Egress-Regeln, Proxy-Einstellungen und die Vertrauenskette der Registry-Zertifikate. Nach Änderungen an internen Zertifizierungsstellen kann beispielsweise die Anwendung dem neuen Zertifikat vertrauen, während die Runtime weiterhin mit einem anderen Trust Store arbeitet.

Wenn nur einzelne Nodes betroffen sind, ist dieser Unterschied besonders aussagekräftig. Dann sollten funktionierende und fehlerhafte Nodes verglichen werden: Runtime-Konfiguration, Netzsegment, Zertifikate und lokale Ressourcen. Ein clusterweiter Neustart würde diese Diagnose eher erschweren als verbessern.

Architektur und lokale Ressourcen nicht vergessen

Ein Image muss auch zur vorgesehenen Plattform passen. In gemischten Umgebungen sollte geprüft werden, ob für die Architektur des Nodes ein passendes Manifest vorliegt. Fehler dieser Art gehören in die Artefaktprüfung, bevor das Release produktiv ausgerollt wird.

Außerdem benötigt die Runtime Platz zum Herunterladen und Entpacken. Ein Registry-Zugriff kann grundsätzlich funktionieren, während der Vorgang lokal an Speicherdruck oder einem Dateisystemproblem scheitert. Hier helfen die vollständigen Runtime- und Node-Meldungen weiter.

Auch Rate Limits und eine überlastete Registry sind mögliche Ursachen. Wenn viele Nodes gleichzeitig dasselbe große Image beziehen, verändert sich die Last deutlich gegenüber einem einzelnen Test. Das Verhalten bei einem vollständigen Wiederanlauf sollte deshalb Bestandteil der Betriebsplanung sein.

Nicht durch ständiges Neuerstellen beschleunigen

Das wiederholte Löschen fehlerhafter Pods beseitigt weder falsche Zugangsdaten noch einen fehlenden Image-Tag. Es erzeugt zusätzliche Vorgänge und kann die zeitliche Einordnung erschweren. Zuerst sollte die konkret gemeldete Ursache korrigiert werden.

Nach der Korrektur wird geprüft, ob ein kontrolliert neu gestarteter Pod das Image beziehen kann und anschließend bereit wird. Dabei ist die gesamte Startfolge relevant: Erfolgreicher Download, Containerstart und bestandene Bereitschaftsprüfung sind drei verschiedene Nachweise.

Für die Pipeline lohnt sich eine explizite Freigabebedingung, die diesen Unterschied abbildet. Falls der Rollout nicht erfolgreich wird, sollte der Fehler mit dem betroffenen Image-Verweis und den relevanten Events sichtbar zurückgemeldet werden.

Wiederanlauf als Produkteigenschaft

Ein produktives System muss seine Images auch dann beziehen können, wenn kein Node mehr einen hilfreichen Cache besitzt. Dafür braucht es verfügbare Artefakte, gültige Zugänge, passende Zertifikate und ausreichend Kapazität in Registry und Netzwerk.

Ein guter Test startet daher gezielt auf einem geeigneten Node ohne das betreffende Image im Cache, statt sich nur auf wiederholte Rollouts derselben Umgebung zu verlassen. Der Test muss kontrolliert erfolgen und keine produktiven Caches wahllos löschen.

Die wichtigste Konsequenz ist organisatorisch: Der Release-Prozess endet bei einer nutzbaren Anwendung. Erst wenn das Image am vorgesehenen Ausführungsort ankommt und der Container betriebsbereit wird, ist aus einem erfolgreichen Build ein erfolgreicher Betrieb geworden.

Technische Quellen