Der Pod wartet, weil das Abbild nicht kommt: falscher Name, falsches Tag, fehlende Zugangsdaten. So liest du die Ursache statt zu raten.
Aufwand:
ca. 15 Min.
Voraussetzung:
kubectl, Zugangsdaten der Registry
Gilt für:
Kubernetes (kubelet und Container-Laufzeitumgebung)
Das Symptom
Der Pod steht auf ErrImagePull, kurz darauf auf ImagePullBackOff, und dort bleibt
er. Kein Absturz, keine Log-Zeile der Anwendung, nichts – denn die Anwendung wurde nie
gestartet. Auf dem eigenen Rechner läuft dasselbe Abbild seit Wochen, im Cluster
passiert gar nichts, und mit jedem Versuch vergeht mehr Zeit bis zum nächsten.
Die „Layer 8“-Wahrheit
Dieser Zustand ist die höflichste Fehlermeldung, die Kubernetes zu bieten hat: Der
Container konnte nicht starten, weil sein Abbild nicht zu beschaffen war. Die
Dokumentation zählt die Gründe trocken auf – ungültiger Name des Abbilds, oder ein
Abruf aus einer privaten Registry ohne hinterlegtes Geheimnis. Der Zusatz BackOff
bedeutet dabei nur, dass es weiter probiert wird, mit wachsender Pause dazwischen, bis
zur fest einprogrammierten Obergrenze von 300 Sekunden.
Der Denkfehler ist fast immer derselbe und hat nichts mit Kubernetes zu tun: Man
verwechselt „ich habe das Abbild gebaut“ mit „der Cluster kann das Abbild holen“. Ein
frisch gebautes Abbild liegt auf dem Laptop. Die Knoten des Clusters sind andere
Rechner, sie holen aus einer Registry, und wenn vor dem Namen kein Registry-Hostname
steht, nehmen sie die öffentliche Docker-Registry an. Dort war das Firmen-Abbild noch
nie. Genauso zuverlässig funktioniert die zweite Variante: Das Geheimnis mit den
Zugangsdaten existiert – nur im falschen Namensraum, denn dort sucht niemand danach.
Besonders tückisch ist der Fall, in dem es gestern noch ging. Abbilder liegen pro
Knoten im Zwischenspeicher, und solange der Pod immer wieder auf demselben Knoten
landet, fällt eine fehlende Anmeldung schlicht nicht auf. Der Tag, an dem der Cluster
einen neuen Knoten bekommt, ist dann der Tag, an dem alle gleichzeitig lernen, dass
diese Zugangsdaten nie funktioniert haben. Die Diagnose kostet dabei genau einen
Befehl: kubectl describe pod nennt in den Ereignissen im Klartext, woran es
gescheitert ist. Was danach folgt, ist Handarbeit an Namen, Tag und Geheimnis – aber
kein Rätselraten mehr.
Die echte, verifizierte Lösung
1000 % faktenbasiert. Jeder Befehl ist real, jeder Pfad existiert. Schritt für Schritt:
1.
Den Zustand des Pods ablesen
In der Übersicht steht `ErrImagePull` oder `ImagePullBackOff`. Beides bedeutet: Der Pod ist einem Knoten zugewiesen, der Container wartet aber noch – die Anwendung selbst wurde nie gestartet.
kubectl get pods
2.
Die eigentliche Fehlermeldung lesen
Die Ereignisliste am Ende der Ausgabe nennt die Wahrheit im Klartext: unbekanntes Abbild, nicht gefundenes Tag, verweigerte Anmeldung oder ein erschöpftes Kontingent der Registry. Ohne diesen Schritt rät man; mit ihm ist die Ursache meist in einer Zeile beantwortet.
kubectl describe pod POD-NAME
3.
Den vollständigen Namen des Abbilds prüfen
Hier steht, was Kubernetes wirklich zu holen versucht – nicht das, was in der Vorlage gemeint war. Fehlt der Registry-Hostname, wird die öffentliche Docker-Registry angenommen. Ein Tippfehler im Tag sieht in der Vorlage harmlos aus und ist hier sofort sichtbar.
kubectl get pod POD-NAME -o jsonpath='{.spec.containers[*].image}'
4.
Das Abbild von Hand ziehen
Die Kubernetes-Anleitung empfiehlt ausdrücklich, den Abruf manuell zu versuchen. Klappt er auf dem eigenen Rechner, aber nicht im Cluster, liegt es an Zugangsdaten oder Netzwerkregeln der Knoten. Klappt er auch hier nicht, ist der Name oder das Tag falsch.
docker pull REGISTRY/NAME:TAG
5.
Zugangsdaten für eine private Registry hinterlegen
Ohne hinterlegte Anmeldung kommt das kubelet an ein privates Abbild nicht heran. Das Geheimnis muss im selben Namensraum liegen wie der Pod, der es benutzt – ein Geheimnis im Namensraum nebenan wird nicht gefunden.
Angelegt allein reicht nicht: Der Pod muss es unter `imagePullSecrets` benennen. Das Feld steht auf Ebene der Pod-Spezifikation, nicht beim Container – eine der häufigsten Verwechslungen in dieser Datei.
Nach der Korrektur zeigt der Ereignisstrom, ob der nächste Versuch durchgeht. Er zeigt auch, wenn die Registry selbst bremst – etwa wegen eines erschöpften Abhol-Kontingents. Das ist dann kein Fehler der Konfiguration, sondern eine Grenze auf der Gegenseite.
kubectl events --for pod/POD-NAME --types=Warning
Häufige Fragen (FAQ)
?Was ist der Unterschied zwischen `ErrImagePull` und `ImagePullBackOff`?
Es ist derselbe Vorgang in zwei Stadien. `ErrImagePull` erscheint beim ersten misslungenen Versuch, das Abbild zu holen. `ImagePullBackOff` erscheint danach und bedeutet, dass Kubernetes es weiter versucht, aber mit wachsender Wartezeit dazwischen. Die Dokumentation formuliert es so: The status `ImagePullBackOff` means that a container could not start because Kubernetes could not pull a container image, und der Zusatz `BackOff` zeige an, dass Kubernetes es mit zunehmender Verzögerung weiter probiert. Diese Verzögerung wächst bis zu einer einkompilierten Grenze von 300 Sekunden, also fünf Minuten. Ein Pod, der nach zehn Minuten immer noch wartet, tut das also nicht aus Trotz, sondern nach Plan.
?Ich habe das Abbild doch gerade gebaut – warum findet es der Cluster nicht?
Weil es auf deinem Rechner liegt und nicht in einer Registry, aus der die Knoten es holen können. Die Kubernetes-Anleitung zur Fehlersuche nennt genau drei Dinge zum Prüfen: ob der Name des Abbilds stimmt, ob es überhaupt in die Registry geschoben wurde, und ob es sich von Hand ziehen lässt. Dazu kommt eine Falle des Namensschemas: Steht vor dem Namen kein Registry-Hostname, nimmt Kubernetes die öffentliche Docker-Registry an – ein Abbild aus der Firmen-Registry wird dann dort gesucht, wo es nie war.
?Warum funktioniert es bei einem Knoten und beim nächsten nicht?
Weil die Abbilder pro Knoten zwischengespeichert werden. Auf einem Knoten liegt das Abbild noch vom letzten Mal, dort startet der Pod klaglos. Ein frisch dazugekommener Knoten muss es wirklich holen – und scheitert dann an fehlenden Zugangsdaten oder einem Tippfehler, der vorher niemandem aufgefallen ist. Verstärkt wird das durch die Abholregeln: Wird kein `imagePullPolicy` angegeben und lautet das Tag `:latest` oder fehlt ganz, setzt Kubernetes die Regel automatisch auf `Always`, holt also bei jedem Start neu.
Belege
Diese Seite ist gegen die folgenden Primärquellen geprüft – Hersteller, Standard oder Gesetzestext. Wer es nicht glaubt, muss es nicht: Da steht, wo es nachzulesen ist.