Fehlersuche nach Plan:
vom Symptom zur Ursache

Pending heißt fast immer: Der scheduler hat keine Entscheidung getroffen. Der Grund steht als Event am Pod, nicht im Log – ein Log gibt es noch gar nicht, weil kein Container existiert.

kubectl describe pod <pod> -n <namespace>
kubectl get events -n <namespace> --field-selector reason=FailedScheduling

Zu wenig CPU oder Memory: Entscheidend ist nicht die Auslastung, sondern die Summe der Requests. Ein Node kann bei 20 % CPU-Last voll belegt sein.

# tatsächliche Last (benötigt metrics-server)
kubectl top nodes
# reservierte Requests pro Node
kubectl describe node <node> | grep -A 8 "Allocated resources"

Lösung: Requests senken oder Kapazität schaffen (Node hinzufügen, andere Workloads verschieben).

nodeSelector oder Affinity passt nicht: Der Pod verlangt Labels, die kein Node trägt.

kubectl get pod <pod> -n <namespace> -o jsonpath='{.spec.nodeSelector}'
kubectl get nodes --show-labels

Lösung: Node-Labels ergänzen oder den Selector korrigieren.

Taints ohne passende Toleration: Der Node wehrt den Pod aktiv ab.

kubectl get nodes -o custom-columns=NAME:.metadata.name,TAINTS:.spec.taints

Lösung: Toleration am Pod ergänzen oder den Taint entfernen, wenn er nicht gewollt war.

Volume fehlt: Wenn describe auf ein ungebundenes PVC zeigt, liegt die Ursache in Abschnitt 5, nicht beim scheduler.

Die genaue Fehlermeldung der Registry steht in den Events des Pods – sie unterscheidet die drei möglichen Ursachen.

kubectl describe pod <pod> -n <namespace>

„not found": Name oder Tag stimmen nicht. Prüfen und im Deployment korrigieren, nicht am laufenden Pod.

„unauthorized": Pull-Secret fehlt, ist falsch oder liegt im falschen Namespace.

kubectl get secrets -n <namespace>
kubectl get pod <pod> -n <namespace> -o jsonpath='{.spec.imagePullSecrets}'

„connection refused" oder Timeout: Die Registry ist vom Node aus nicht erreichbar – Netz, Proxy, DNS oder Firewall. Der Test gehört auf den Node, nicht auf den Laptop.

# Debug-Pod auf dem Node, Host-Dateisystem liegt unter /host
kubectl debug node/<node> -it --image=busybox
wget -S --spider https://<registry-host>/v2/
# auf OpenShift stattdessen:
oc debug node/<node>

Hier gibt es bereits ein Log – und zwar zwei: das des aktuellen und das des vorherigen Versuchs. Das interessante ist meist das vorherige, weil der aktuelle Container oft noch gar nicht gestartet ist.

kubectl logs <pod> -n <namespace>
kubectl logs <pod> -n <namespace> --previous

Anwendungsfehler: Environment-Variablen, ConfigMaps, Abhängigkeiten prüfen und im Deployment beziehungsweise in ConfigMap/Secret korrigieren.

OOMKilled: Der Container hat sein Memory-Limit gerissen. Der Beweis steht im letzten Terminierungsgrund, nicht in den Logs.

kubectl get pod <pod> -n <namespace> \
  -o jsonpath='{.status.containerStatuses[*].lastState.terminated.reason}'
kubectl describe pod <pod> -n <namespace> | grep -A 5 "Limits:"

Lösung: Memory-Limit anheben oder den Speicherverbrauch der Anwendung begrenzen (Heap-Größe, Worker-Anzahl).

Exit Code 137 oder 143: 137 ist 128+9 (SIGKILL), 143 ist 128+15 (SIGTERM). Das sind Signale, keine Diagnosen – sie sagen, dass jemand beendet hat, nicht wer.

READY 0/1 bei Running: Der Container läuft, die Readiness-Probe ist nicht erfüllt. Pfad, Port oder Startzeit der Probe passen nicht zur Anwendung.

kubectl describe pod <pod> -n <namespace> | grep -A 3 Readiness

READY 1/1, aber fachlich kaputt: Am Service vorbei direkt auf den Pod testen. Antwortet er hier korrekt, liegt der Fehler im Service oder Ingress – nicht in der Anwendung.

kubectl port-forward pod/<pod> 8080:<container-port> -n <namespace>
curl -sv localhost:8080

Error oder Unknown: Meist meldet der Node nicht mehr. Erst die Objektsicht, dann weiter in Abschnitt 2.

kubectl describe pod <pod> -n <namespace>
kubectl get events -n <namespace> --field-selector involvedObject.name=<pod>

Die Frage lautet nicht „was ist kaputt", sondern „auf welcher Ebene fängt es an". Ein nicht erreichbarer Service kann an Pods, Service, Ingress oder DNS liegen – der Test von innen nach außen entscheidet, welcher Abschnitt zuständig ist.

# von innen nach außen: Pod, dann Service, dann Ingress
kubectl get pods,svc,ingress -n <namespace>

Pending, ImagePullBackOff, CrashLoopBackOff, NotReady, Terminating: Diese Wörter sind keine Beschreibung des Unwohlseins, sondern Zweigadressen. Wer den Status überliest und direkt zu den Logs springt, öffnet in der Hälfte der Fälle ein Log, das es noch gar nicht gibt.

Events zeigen, was Kubernetes selbst getan oder verweigert hat – Scheduling, Pull, Mount, Probe. Logs zeigen, was die Anwendung getan hat. Vor dem ersten Containerstart existieren nur Events.

kubectl describe <ressource> <name> -n <namespace>
kubectl get events -n <namespace> --sort-by=.metadata.creationTimestamp

Jeder Zweig endet mit einer konkreten Ursache: falsches Label, fehlendes Secret, zu kleines Limit, falscher Port. Solange nur ein Verdacht besteht, ist der Zweig nicht zu Ende – ein Fix auf Verdacht erzeugt zwei Fehler statt einem.

Änderungen gehören in das Manifest, aus dem das Objekt entsteht – Deployment, ConfigMap, Helm-Werte, Git-Repository. Ein kubectl edit am Pod überlebt den nächsten Neustart nicht, in einer GitOps-Umgebung nicht einmal die nächste Synchronisation.

# nach dem Rollout: läuft die neue Generation wirklich?
kubectl rollout status deployment/<name> -n <namespace>

Nachweis heißt: derselbe Test, der den Fehler gezeigt hat, ist jetzt grün – nicht „der Pod ist Running". Bei Netzwerkfehlern also erneut der Verbindungstest, bei OOM ein Blick auf die Neustartzähler über eine gewisse Zeit.

kubectl get pod <pod> -n <namespace> \
  -o jsonpath='{.status.containerStatuses[*].restartCount}'

Die meisten Vorfälle in diesem Baum haben eine vorbeugende Maßnahme: Requests und Limits gegen Verdrängung und OOM, Readiness- und Liveness-Probes gegen stillen Ausfall, Monitoring auf Neustartzähler und Pending-Pods gegen späte Entdeckung. Ohne diesen Schritt wird derselbe Zweig in zwei Wochen erneut durchlaufen.