kubectl Debugging Cheatsheet: 12 Befehle für Production-Incidents

TL;DR - In Production-Incidents zählt Reihenfolge mehr als Wissen. Dieser Cheatsheet ist die Reihenfolge, die unsere Engineers bei Kunden täglich nutzen: erst get, dann describe, dann logs, dann events, dann debug. Wer diese 12 Befehle in der richtigen Reihenfolge beherrscht, löst 90% aller Pod-Probleme in unter 5 Minuten.

Die Reihenfolge ist der Trick

Die meisten Engineers springen direkt zu kubectl logs und stehen dann ratlos da, wenn der Pod gar nicht erst gestartet ist. Production-Debugging hat eine feste Pyramide:

1. Status - was sagt der Cluster über den Pod?
2. Beschreibung - was sagen Events und Conditions?
3. Logs - was hat der Container selbst gesagt?
4. Cluster-Events - was hat der Scheduler / Kubelet gesagt?
5. Live-Inspection - was sehe ich, wenn ich reingehe?

1. Status - schnell scannen

kubectl get pods -A --field-selector=status.phase!=Running

Zeigt sofort alle Pods, die nicht laufen - Cluster-weit. Erste Frage in jedem Incident.

kubectl get pod <name> -o wide

Zeigt Node, IP, Restart-Count. Hohe Restart-Counts = Container crashed wiederholt = OOM oder Liveness-Probe-Fail.

2. Describe - der wichtigste Befehl überhaupt

kubectl describe pod <name>

Scrolle direkt zum Bereich Events: am Ende. Dort steht buchstäblich, warum der Pod-Status so ist, wie er ist:

Events:
  Type     Reason          Age   From               Message
  ----     ------          ----  ----               -------
  Warning  FailedScheduling 2m   default-scheduler  0/3 nodes are available: 3 Insufficient memory

Das ist die Antwort. Kein Logs-Lesen nötig.

3. Logs - wenn der Container überhaupt gestartet ist

kubectl logs <pod> -c <container> --tail=100
kubectl logs <pod> --previous          # vorheriger Crash
kubectl logs <pod> -f                  # stream

Der --previous-Switch ist der Trick: Wenn der Pod in CrashLoopBackOff ist, sind die “aktuellen” Logs leer - der Container ist ja noch nicht gestartet. Du brauchst die Logs des vorherigen Crashs.

4. Cluster-Events - der unterschätzte Schatz

kubectl get events --sort-by=.lastTimestamp -A | tail -30

Zeigt zeitlich sortiert, was im Cluster passiert ist - Scheduler-Entscheidungen, Image-Pulls, Volume-Mounts. Wenn describe pod nichts hergibt, hilft das fast immer.

5. Ephemeral Debug Container - der Game-Changer

Seit Kubernetes 1.25 stable. Funktioniert auch bei distroless-Images ohne Shell:

kubectl debug -it <pod> --image=busybox --target=<container>

Du landest in einem neuen Container, der den Process-Namespace und Network-Namespace mit dem Original-Container teilt. Du siehst dessen Prozesse mit ps, kannst dessen Netzwerk mit nc/curl testen, und kannst auf /proc/1/root zugreifen, um sein Filesystem zu sehen.

6. Node-Probleme finden

kubectl describe node <name> | grep -A 10 Conditions
kubectl top nodes
kubectl top pods -A --sort-by=memory

Wenn Pods pending sind oder evicted werden, liegt es fast immer am Node - Memory-Pressure, Disk-Pressure oder NotReady. kubectl top zeigt dir, wer der Schuldige ist.

7. Network-Issues

kubectl run debug --rm -it --image=nicolaka/netshoot -- /bin/bash

Im netshoot-Container hast du dig, nslookup, tcpdump, curl, nmap. Innerhalb des Pods kannst du DNS-Probleme, Service-Resolution und NetworkPolicies testen.

Die 12 wichtigsten in einem Spickzettel

#	Befehl	Wann
1	kubectl get pods -A --field-selector=status.phase!=Running	Erst-Scan
2	kubectl get pod <name> -o wide	Restart-Count, Node
3	kubectl describe pod <name>	Events lesen - 80% der Fälle
4	kubectl logs <pod> --previous	Bei CrashLoopBackOff
5	kubectl logs <pod> -f --tail=100	Live-Logs
6	kubectl get events --sort-by=.lastTimestamp	Wenn describe nicht hilft
7	kubectl debug -it <pod> --image=busybox --target=<c>	Distroless / shell-los
8	kubectl describe node <name>	Bei Pending Pods
9	kubectl top pods -A --sort-by=memory	Memory-Pressure-Suche
10	kubectl get all -n <ns>	Vollständiger Namespace-Scan
11	kubectl exec -it <pod> -- /bin/sh	Live-Inspection wenn Shell da ist
12	kubectl auth can-i --list -n <ns>	RBAC-Probleme

Wie es weitergeht

Im 1-Tag-Intensiv-Workshop Kubernetes Debugging spielen wir 8 echte Production-Incidents nach - CrashLoopBackOff, OOMKilled, ImagePullBackOff, NetworkPolicy-Block, Pending Pods, evicted Pods, DNS-Fail, Liveness-Probe-Death-Spiral - und drillen die Workflows, bis sie sitzen.

Wenn du erst mal selbst debuggen willst: Lade dir das PDF-Cheatsheet mit allen 12 Befehlen + Decision-Tree herunter. (Kommt bald - abonniere unseren RSS-Feed für Updates.)