Beherrschung von kubectl logs und describe für effizientes Pod-Debugging

Wenn ein Kubernetes-Pod ausfällt, sagen Ihnen kubectl describe und kubectl logs normalerweise, wo Sie als Nächstes suchen müssen. describe erklärt, was Kubernetes zu tun versucht hat. logs zeigt, was der Container vor, während oder nach dem Fehler geschrieben hat.

Diese Befehle bieten unterschiedliche, aber sich ergänzende Einblicke in den Zustand und die Historie eines Kubernetes-Pods. kubectl describe liefert die Metadaten, den Status, die Umgebungsvariablen und, entscheidend, eine Historie der System-Ereignisse des Pods. kubectl logs stellt die Standardausgabe (stdout) und Standardfehlerausgabe (stderr) bereit, die von der containerisierten Anwendung selbst erzeugt wurden.

Der Trick besteht darin, sie in der richtigen Reihenfolge zu verwenden. Wenn der Pod nie eingeplant wurde, helfen Logs nicht. Wenn der Pod startet und beendet wird, sagen Ereignisse möglicherweise nur, dass er abgestürzt ist; die Anwendungslogs erklären normalerweise, warum.

---

Der Drei-Schritte-Pod-Debugging-Workflow

Bevor wir uns mit den Befehlen befassen, ist es hilfreich, den typischen Debugging-Workflow zu verstehen:

1. Status prüfen: Verwenden Sie kubectl get pods, um den Fehlerzustand zu identifizieren (Pending, CrashLoopBackOff, ImagePullBackOff usw.).
2. Kontext und Ereignisse abrufen: Verwenden Sie kubectl describe pod, um zu verstehen, warum der Zustandsübergang stattgefunden hat (z. B. Scheduler fehlgeschlagen, Liveness-Probe fehlgeschlagen, Volume konnte nicht gemountet werden).
3. Anwendungsausgabe überprüfen: Verwenden Sie kubectl logs, um das Laufzeitverhalten der Anwendung zu untersuchen (z. B. Konfigurationsfehler, Datenbankverbindungsfehler, Stack-Traces).

1. kubectl describe: Das System-Triage-Werkzeug

kubectl describe ist der erste Befehl, den Sie ausführen sollten, wenn sich ein Pod schlecht verhält. Er zeigt keine Anwendungsausgabe, liefert aber die kritischen Metadaten und die Historie, die Kubernetes selbst über den Pod aufgezeichnet hat.

Grundlegende Verwendung

Die grundlegende Verwendung erfordert nur den Pod-Namen:

kubectl describe pod my-failing-app-xyz789

Verwenden Sie Namespaces explizit, wenn Sie sich nicht im Standard-Namespace befinden:

kubectl describe pod my-failing-app-xyz789 -n payments

Wenn Sie nur das Deployment oder Label kennen, finden Sie zuerst den Pod:

kubectl get pods -n payments -l app=checkout -o wide

Wichtige Abschnitte in der Ausgabe

Wenn Sie die Ausgabe von describe überprüfen, konzentrieren Sie sich auf diese kritischen Abschnitte:

A. Status und Zustand

Betrachten Sie das Feld Status oben und überprüfen Sie dann die einzelnen Containerzustände innerhalb des Pods. Dies zeigt Ihnen, ob der Container Running, Waiting oder Terminated ist, und liefert den Grund für diesen Zustand.

Feld	Häufiger Status/Grund	Bedeutung
Status	Pending	Pod wartet auf die Einplanung oder hat fehlende Ressourcen.
Reason	ContainerCreating	Container-Laufzeitumgebung zieht das Image oder führt das Setup aus.
State	Waiting / Reason: CrashLoopBackOff	Der Container wurde gestartet und wiederholt beendet.
State	Terminated / Exit Code	Der Container hat die Ausführung abgeschlossen. Exit-Codes ungleich Null deuten normalerweise auf Fehler hin.

B. Container-Konfiguration

Dieser Abschnitt überprüft, ob Ihre Umgebungsvariablen, Ressourcenanforderungen/-grenzen, Volume-Mounts und Liveness-/Readiness-Proben korrekt definiert sind und mit dem von Ihnen angewendeten Manifest übereinstimmen.

C. Der Abschnitt Events (entscheidend)

Der Abschnitt Events am Ende der Ausgabe ist wohl der wertvollste Teil. Er bietet eine chronologische Übersicht darüber, was die Kubernetes-Steuerungsebene mit und für den Pod getan hat, einschließlich Warnungen und Fehlern.

Häufige Fehler, die durch Events aufgedeckt werden:

• Scheduling-Probleme: Warning FailedScheduling: Zeigt an, dass der Scheduler keinen geeigneten Knoten finden konnte (z. B. aufgrund von Ressourcenbeschränkungen, Knoten-Taints oder Affinitätsregeln).
• Image-Pull-Fehler: Warning Failed: ImagePullBackOff: Zeigt an, dass der Imagename falsch ist, der Tag nicht existiert oder Kubernetes keine Berechtigungen hat, um aus einer privaten Registry zu ziehen.
• Volume-Fehler: Warning FailedAttachVolume: Zeigt Probleme beim Anschließen von externem Speicher an.

Tipp: Wenn der Abschnitt Events sauber ist und der Container gestartet wurde, liegt das Problem oft an der Anwendung: eine falsche Umgebungsvariable, fehlgeschlagene Migration, fehlendes Secret, unerreichbare Abhängigkeit oder ein Prozess, der sofort beendet wird.

2. kubectl logs: Überprüfung der Anwendungsausgabe

Wenn describe zeigt, dass der Pod erfolgreich eingeplant wurde und Container zu laufen versuchten, besteht der nächste Schritt darin, die Standardausgabeströme mit kubectl logs zu überprüfen.

Grundlegender Log-Abruf und Echtzeit-Streaming

Um die aktuellen Logs für den primären Container in einem Pod anzuzeigen:

# Alle Logs bis zum aktuellen Zeitpunkt abrufen
kubectl logs my-failing-app-xyz789

# Logs in Echtzeit streamen (nützlich zur Überwachung des Starts)
kubectl logs -f my-failing-app-xyz789

Umgang mit Multi-Container-Pods

Für Pods, die das Sidecar-Muster oder andere Multi-Container-Designs verwenden, müssen Sie mit dem Flag -c oder --container angeben, welche Container-Logs Sie anzeigen möchten.

# Logs für den 'sidecar-proxy'-Container innerhalb des Pods anzeigen
kubectl logs my-multi-container-pod -c sidecar-proxy

# Logs für den Hauptanwendungscontainer streamen
kubectl logs -f my-multi-container-pod -c main-app

Debuggen von Neustart-Containern (--previous)

Eines der häufigsten Debugging-Szenarien ist der Zustand CrashLoopBackOff. Wenn ein Container neu startet, zeigt kubectl logs nur die Ausgabe des aktuellen (fehlgeschlagenen) Versuchs, die oft nur die Startmeldung vor dem Absturz enthält.

Um die Logs der vorherigen, beendeten Instanz anzuzeigen – die den eigentlichen Fehler enthalten, der den Exit verursacht hat – verwenden Sie das Flag --previous (-p):

# Logs der vorherigen, abgestürzten Container-Instanz anzeigen
kubectl logs my-crashloop-pod --previous

# Bei Bedarf mit der Containerspezifikation kombinieren
kubectl logs my-crashloop-pod -c worker --previous

Begrenzung der Ausgabe

Bei Logs mit hohem Volumen kann das Abrufen des gesamten Verlaufs langsam oder überwältigend sein. Verwenden Sie --tail, um die Ausgabe auf die letzten N Zeilen zu beschränken.

# Nur die letzten 50 Zeilen der Container-Logs anzeigen
kubectl logs my-high-traffic-app --tail=50

Sie können auch Zeitstempel und ein Zeitfenster hinzufügen:

kubectl logs my-high-traffic-app --tail=100 --timestamps
kubectl logs my-high-traffic-app --since=10m

Für ein Deployment können neuere kubectl-Versionen Logs über den Workload-Namen abrufen:

kubectl logs deploy/checkout-api -n payments --tail=100

Wenn das zu breit ist, verwenden Sie einen Label-Selektor:

kubectl logs -n payments -l app=checkout --all-containers=true --tail=50

3. Kombination von Techniken für fortgeschrittene Diagnosen

Effektives Debugging beinhaltet oft das schnelle Wechseln zwischen describe und spezifischen logs-Befehlen.

Fallstudie: Diagnose eines Liveness-Probe-Fehlers

Stellen Sie sich einen Pod vor, der im Status Running steckt, aber gelegentlich neu startet, was zu Störungen führt.

Schritt 1: Überprüfen Sie describe auf die Systemsicht.

kubectl describe pod web-server-dpl-abc

Die Ausgabe zeigt im Abschnitt Events:

Type     Reason      Age   From               Message
----     ------      ----  ----               -------
Warning  Unhealthy   2s    kubelet, node-a01  Liveness probe failed: HTTP GET http://10.42.0.5:8080/health failed: 503 Service Unavailable

Schlussfolgerung aus Schritt 1: Der Container läuft, aber die Liveness-Probe schlägt mit einem 503-Fehler fehl, was Kubernetes dazu veranlasst, den Container neu zu starten.

Schritt 2: Überprüfen Sie logs auf den Anwendungskontext.

Untersuchen Sie nun, warum die Anwendung einen 503-Status zurückgibt, was ein Fehler auf Anwendungsebene ist.

kubectl logs web-server-dpl-abc --tail=200

Die Log-Ausgabe zeigt:

2023-10-26 14:01:15 ERROR Datenbankverbindungsfehler: Zeitüberschreitung beim Verbinden mit DB-Instanz 192.168.1.10

Endgültige Schlussfolgerung: Der Pod startet aufgrund einer fehlschlagenden Liveness-Probe neu, und die Probe schlägt fehl, weil die Anwendung keine Verbindung zur Datenbank herstellen kann. Das Problem ist die externe Netzwerk- oder Datenbankkonfiguration, nicht der Container selbst.

Fallstudie: Ausstehender Pod ohne Logs

Ein Pod im Status Pending hat oft keine nützlichen Container-Logs, da noch kein Container gestartet wurde.

kubectl get pod report-worker-6f9c7b9b7d-f2q8m -n analytics

Ausgabe:

NAME                                  READY   STATUS    RESTARTS   AGE
report-worker-6f9c7b9b7d-f2q8m        0/1     Pending   0          4m

Gehen Sie direkt zu describe:

kubectl describe pod report-worker-6f9c7b9b7d-f2q8m -n analytics

Events könnten zeigen:

Warning  FailedScheduling  default-scheduler  0/6 nodes are available: 6 Insufficient memory.

Das ist kein Anwendungsfehler. Der Pod fordert mehr Speicher an, als der Scheduler bereitstellen kann. Der nächste Schritt ist die Überprüfung der Deployment-Anforderungen, der Cluster-Kapazität, der Knoten-Taints und des Autoscaler-Verhaltens:

kubectl get deploy report-worker -n analytics -o yaml
kubectl top nodes

Fallstudie: ImagePullBackOff

Bei ImagePullBackOff sind Logs normalerweise leer, da das Container-Image nie gestartet wurde. describe liefert den nützlichen Fehler:

kubectl describe pod api-7dfb9c8b7f-bd2p9 -n staging

Häufige Ereignismeldungen sind ein nicht existierender Image-Tag, ein Authentifizierungsfehler gegen eine private Registry oder ein DNS-/Netzwerkproblem beim Erreichen der Registry. Die Behebung könnte so einfach sein wie das Korrigieren des Tags:

kubectl set image deploy/api api=registry.example.com/api:2026-05-24 -n staging

Oder es könnte die Überprüfung des Image-Pull-Secrets erfordern:

kubectl get secret regcred -n staging
kubectl describe serviceaccount default -n staging

Fallstudie: Multi-Container-Pod mit einer ruhigen App

Sidecars können das Signal verbergen, wenn Sie den falschen Container betrachten. Listen Sie zuerst die Containernamen auf:

kubectl get pod checkout-84f7c9d7bf-px5mx -n payments \
  -o jsonpath='{.spec.containers[*].name}{"\n"}'

Dann überprüfen Sie jeden gezielt:

kubectl logs checkout-84f7c9d7bf-px5mx -n payments -c checkout --tail=100
kubectl logs checkout-84f7c9d7bf-px5mx -n payments -c envoy --tail=100

Wenn die App-Logs ruhig sind, aber die Proxy-Logs Upstream-Verbindungsfehler zeigen, ist der Pod aus Kubernetes-Sicht möglicherweise gesund, während der Datenverkehr aufgrund der Service-Mesh- oder Proxy-Konfiguration immer noch fehlschlägt.

Best Practices und Warnungen

Praxis	Befehl	Begründung
Immer vorherige Logs prüfen	kubectl logs --previous	Notwendig für die Diagnose von CrashLoopBackOff. Der kritische Fehler liegt fast immer im vorherigen Lauf.
Container angeben	kubectl logs -c <name>	Vermeidet Mehrdeutigkeit in Multi-Container-Pods und verhindert das Abrufen von Logs von unbeabsichtigten Sidecars.
Labels für Bulk-Operationen verwenden	kubectl logs -l app=frontend -f	Ermöglicht das gleichzeitige Streamen von Logs von mehreren Pods, die einem Selektor entsprechen (nützlich für Rolling Updates).
Warnung: Log-Rotation	N/A	Kubernetes-Knoten führen eine Log-Rotation durch. Logs, die älter sind als die konfigurierte Aufbewahrungsrichtlinie des Knotens (oft ein paar Tage oder basierend auf der Größe), werden gelöscht und sind über kubectl logs nicht mehr verfügbar. Verwenden Sie eine externe zentralisierte Logging-Lösung (z. B. Fluentd, Loki, Elastic Stack) für die Langzeitspeicherung.

Was diese Befehle Ihnen nicht sagen können

kubectl logs zeigt nur Container-stdout und stderr, die vom Knoten aufbewahrt werden. Wenn die Anwendung in eine Datei innerhalb des Containers schreibt, zeigt kubectl logs möglicherweise nichts an. Das ist ein Problem des Logging-Designs, kein kubectl-Problem.

kubectl describe zeigt den Kubernetes-Objektzustand und aktuelle Ereignisse, aber Ereignisse sind keine dauerhaften Audit-Logs. Alte Ereignisse laufen aus. Kopieren Sie für langwierige Untersuchungen die relevante Ausgabe in die Incident-Notizen.

Keiner dieser Befehle ersetzt Metriken. Ein Pod kann laufen und normal protokollieren, während CPU-Drosselung, Speicherdruck oder nachgelagerte Latenz zu benutzersichtbaren Problemen führen. Nach describe und logs sind die nächsten Befehle oft:

kubectl top pod -n payments
kubectl top node
kubectl get events -n payments --sort-by=.lastTimestamp

Verwenden Sie zuerst describe, wenn Kubernetes den Pod nicht erstellen oder am Laufen halten konnte. Verwenden Sie zuerst logs, wenn der Pod läuft, aber die Anwendung sich falsch verhält. Wechseln Sie zwischen ihnen, bis Sie Plattformsymptome von Anwendungssymptomen trennen können.

Ein wiederverwendbarer Debugging-Ablauf

Wenn Sie unter Druck stehen, verwenden Sie jedes Mal denselben Ablauf:

kubectl get pod <pod> -n <namespace> -o wide
kubectl describe pod <pod> -n <namespace>
kubectl logs <pod> -n <namespace> --all-containers=true --tail=100
kubectl logs <pod> -n <namespace> --all-containers=true --previous --tail=100
kubectl get events -n <namespace> --sort-by=.lastTimestamp

Die Reihenfolge ist wichtig. get pod -o wide zeigt Ihnen den Knoten, die Pod-IP, die Anzahl der Neustarts und das Alter. describe zeigt Ihnen Details zu Scheduling, Image, Volume, Probe und Containerzustand. Aktuelle Logs zeigen, was der laufende Container gerade tut. Vorherige Logs erfassen den bereits erfolgten Absturz. Ereignisse zeigen, ob dasselbe Problem im gesamten Namespace auftritt.

Für Deployments fügen Sie eine Rollout-Überprüfung hinzu:

kubectl rollout status deploy/<name> -n <namespace>
kubectl describe deploy/<name> -n <namespace>
kubectl get rs -n <namespace> -l app=<label>

Manchmal stammt der Pod, den Sie debuggen, von einem alten ReplicaSet während eines Rollouts. Wenn Sie das Deployment beheben, aber weiterhin Logs von einem alten, sich beendenden Pod lesen, können Sie eine halbe Stunde lang dem falschen Problem nachjagen.

Neustarts richtig interpretieren

Die Spalte RESTARTS ist ein Hinweis, keine Diagnose. Eine Neustartanzahl von 1 nach einem Knoten-Drain kann harmlos sein. Eine Neustartanzahl, die jede Minute steigt, ist ein aktiver Fehler. Verwenden Sie describe, um den letzten Zustand zu überprüfen:

Last State:     Terminated
  Reason:       Error
  Exit Code:    1
  Started:      Sun, 24 May 2026 10:14:02 +0800
  Finished:     Sun, 24 May 2026 10:14:07 +0800

Ein Exit-Code von 1 bedeutet normalerweise, dass der Prozess mit einem allgemeinen Anwendungsfehler beendet wurde. 137 bedeutet oft, dass der Prozess getötet wurde, häufig weil er Speicherlimits überschritten hat, obwohl Sie dies mit dem Feld Reason und dem Knoten-/Container-Laufzeitkontext bestätigen sollten. 143 tritt häufig auf, wenn ein Prozess während der normalen Beendigung SIGTERM empfängt. Behandeln Sie nicht jeden Exit-Code ungleich Null als dieselbe Art von Fehler.

Wenn Speicher vermutet wird, suchen Sie nach:

Reason:       OOMKilled
Exit Code:    137

Vergleichen Sie dann das Container-Limit mit der tatsächlichen Nutzung:

kubectl describe pod <pod> -n <namespace> | rg -A5 'Limits|Requests'
kubectl top pod <pod> -n <namespace>

Wenn metrics-server nicht installiert ist, funktioniert kubectl top nicht. Verwenden Sie in diesem Fall das Metriksystem Ihrer Plattform oder knotenbezogene Werkzeuge.