kubectl debug: Der komplette Guide zum Troubleshooting von Pods & Nodes

kubectl debug vs. kubectl logs vs. kubectl describe

kubectl debug, kubectl logs und kubectl describe sind allesamt Troubleshooting-Befehle, dienen aber unterschiedlichen Zwecken. kubectl logs ruft die Anwendungsausgabe ab, kubectl describe zeigt Details und Events zu Kubernetes-Ressourcen, und kubectl debug bietet interaktiven Zugriff für die Live-Analyse.

kubectl logs

Der Befehl kubectl logs zeigt die stdout- und stderr-Ausgaben von Containern an. Er wird häufig genutzt, um Anwendungsabstürze, Startfehler oder Laufzeitfehler zu identifizieren.

kubectl logs my-pod

Bei Pods mit mehreren Containern geben Sie den Containernamen an:

kubectl logs my-pod -c app-container

Dieser Befehl ist leichtgewichtig und sicher, da er den Pod nicht verändert und keine neuen Container erstellt.

kubectl describe

Der Befehl kubectl describe liefert detaillierte Informationen zu Kubernetes-Ressourcen, darunter Labels, Conditions, gemountete Volumes und aktuelle Events.

kubectl describe pod my-pod

Dieser Befehl eignet sich zur Diagnose von Problemen wie:

• Fehlgeschlagenes Scheduling
• Image-Pull-Fehler
• Fehlgeschlagene Probes
• Ressourcenbeschränkungen
• CrashLoopBackOff-Events

Anders als kubectl logs konzentriert er sich auf den Zustand der Kubernetes-Objekte statt auf die Anwendungsausgabe.

kubectl debug

Der Befehl kubectl debug ermöglicht interaktives Troubleshooting, indem er ephemere Container anhängt oder temporäre Debug-Pods erstellt.

kubectl debug my-pod -it --image=busybox

Dieser Ansatz hilft, wenn Logs und Ressourcenbeschreibungen nicht ausreichen. Sie können zum Beispiel:

• Netzwerkverbindungen prüfen
• Dateisysteminhalte untersuchen
• Tools zur Prozessanalyse ausführen
• Minimale Container ohne Shell debuggen
• Probleme auf Node-Ebene untersuchen

Da temporäre Debugging-Umgebungen erstellt werden, bietet kubectl debug tieferen Zugriff als die anderen Befehle – bei minimalen Änderungen an produktiven Workloads.

Praktische Beispiele für kubectl debug

Netzwerkverbindungen debuggen

Nutzen Sie einen Debug-Container, um DNS, Service Discovery und ausgehende Netzwerkzugriffe aus dem Netzwerk-Namespace des Pods zu testen.

kubectl debug my-pod -it --image=busybox --target=my-container

Führen Sie im Debug-Container Befehle aus wie:

nslookup kubernetes.default
wget -qO- http://my-service.default.svc.cluster.local
ping 10.0.0.10

Das ist nützlich, wenn das Anwendungs-Image keine Tools wie nslookup, curl oder ping enthält.

Pod im CrashLoopBackOff debuggen

Erstellen Sie für einen Pod, der ständig neu startet, eine Kopie zur Untersuchung. So bleibt der ursprüngliche Workload unverändert.

kubectl debug my-pod --copy-to=my-pod-debug -it --image=ubuntu

In der Pod-Kopie können Sie Umgebungsvariablen, gemountete Dateien, Konfiguration und Netzwerkzugriff prüfen:

env
ls -la /etc/config
cat /etc/config/app.conf

So lassen sich fehlende Dateien, fehlerhafte Umgebungswerte oder Laufzeitabhängigkeiten identifizieren.

Debugging mit geteiltem Prozess-Namespace

Nutzen Sie das Teilen des Prozess-Namespace, wenn Sie Prozesse aus einem anderen Container des Pods untersuchen müssen.

kubectl debug my-pod \
  --copy-to=my-pod-debug \
  --share-processes \
  -it \
  --image=ubuntu

Prüfen Sie im Debug-Container die laufenden Prozesse:

ps aux
top

Das ist nützlich zur Untersuchung hängender Prozesse, Zombie-Prozesse oder unerwarteter Kindprozesse.

Debugging mit eigenem Image

Verwenden Sie ein eigenes Debug-Image, wenn Standard-Images nicht die benötigten Tools enthalten.

kubectl debug my-pod -it \
  --image=my-registry.example.com/debug-tools:latest \
  --target=my-container

Ein eigenes Image kann Tools wie curl, dig, tcpdump, strace oder Datenbank-Clients enthalten. So bleiben Produktions-Images klein, während bei Bedarf trotzdem tiefgehendes Troubleshooting möglich ist.

Best Practices für den Einsatz von kubectl debug

Hier einige bewährte Vorgehensweisen für die Nutzung dieses Befehls.

1. Erst Observability, dann die interaktive Session

Nutzen Sie kubectl logs, kubectl describe, Events, Metriken und Traces, bevor Sie eine interaktive Debug-Session starten. Diese Tools sind schneller, sicherer und reichen oft aus, um das Problem zu identifizieren.

kubectl logs my-pod
kubectl describe pod my-pod
kubectl get events --sort-by=.metadata.creationTimestamp

So lässt sich klären, ob das Problem an der Anwendung, am Scheduling, an Probes, Ressourcenlimits, am Netzwerk oder an der Kubernetes-Konfiguration liegt. kubectl describe zeigt beispielsweise Image-Pull-Fehler, fehlgeschlagene Readiness Probes oder Fehler beim Mounten von Volumes, bevor Sie Zeit in die direkte Untersuchung des Containers investieren.

Greifen Sie zu kubectl debug, wenn die verfügbaren Signale das Problem nicht erklären oder wenn Sie den Laufzeitzustand aus der Umgebung des Pods heraus untersuchen müssen.

2. Ephemere Container zum Untersuchen nutzen, nicht für Anwendungsänderungen

Ephemere Container sind für das Troubleshooting gedacht. Nutzen Sie sie nicht, um in einem laufenden Workload Dateien zu patchen, Dienste neu zu starten, Abhängigkeiten zu installieren oder das Anwendungsverhalten zu verändern.

Nutzen Sie sie, um den Zustand zu untersuchen, Diagnosebefehle auszuführen und Befunde zu sammeln:

kubectl debug my-pod -it --image=busybox --target=my-container

Sie können zum Beispiel die DNS-Auflösung prüfen, gemountete Dateien untersuchen, die Erreichbarkeit von Services testen oder laufende Prozesse einsehen. Diese Aktionen helfen zu verstehen, was passiert, ohne den Workload zu verändern.

Jede Korrektur sollte im Quellcode, im Container-Image, in den Manifesten oder in der Deployment-Pipeline erfolgen. So bleibt das Produktionsverhalten reproduzierbar, und es entstehen keine einmaligen manuellen Änderungen, die nach einem Pod-Neustart wieder verschwinden.

3. Debug-Container statt zusätzlicher Tools im Produktions-Image

Vermeiden Sie es, Shells, Paketmanager und Netzwerk-Tools nur fürs Troubleshooting in Produktions-Images zu installieren. Diese Tools vergrößern das Image und können die Angriffsfläche des Containers erweitern.

Halten Sie Anwendungs-Images stattdessen klein und nutzen Sie bei Bedarf ein separates Debug-Image:

kubectl debug my-pod -it --image=nicolaka/netshoot --target=my-container

Das ist besonders nützlich für minimale Images wie Distroless- oder Scratch-basierte Container, die oft keine Shell enthalten. Ein Debug-Container kann Tools wie curl, dig, tcpdump, ss und ip bereitstellen, ohne das Produktions-Image zu verändern.

Dieser Ansatz sorgt zudem für eine klare Trennung: Das Anwendungs-Image führt den Workload aus, während das Debug-Image nur in kontrollierten Troubleshooting-Sessions zum Einsatz kommt.

4. Freigegebene, sichere Debugging-Images verwenden

Debug-Images enthalten oft leistungsstarke Tools wie tcpdump, strace, curl, dig, Paketmanager und Shell-Utilities. Verwenden Sie ausschließlich freigegebene Images aus vertrauenswürdigen Registries.

Pinnen Sie Image-Versionen, statt Floating Tags zu verwenden:

kubectl debug my-pod -it --image=registry.example.com/debug-tools:1.4.2

Freigegebene Images sollten auf Schwachstellen gescannt und aktuell gehalten werden. Sie sollten die Tools enthalten, die Ihre Teams tatsächlich benötigen – ohne überflüssige Pakete.

Auch der Zugriff sollte per RBAC kontrolliert werden. Nicht jeder Benutzer sollte ephemere Container erstellen, sich an sensible Workloads anhängen oder Debug-Sessions auf Node-Ebene starten dürfen. Node-Debugging kann Host-Dateisysteme und Informationen auf Systemebene offenlegen und sollte daher auf vertrauenswürdige Operatoren beschränkt sein – kombinieren Sie das nach Möglichkeit mit dem Flag --profile (restricted oder baseline), um nicht mehr Zugriff zu gewähren, als die Session benötigt.

5. Debug-Pods aufräumen und die Session dokumentieren

Entfernen Sie kopierte Debug-Pods nach dem Troubleshooting, um unnötige Ressourcennutzung und Unordnung im Cluster zu vermeiden.

kubectl delete pod my-pod-debug

Ephemere Container, die zu bestehenden Pods hinzugefügt wurden, lassen sich nicht aus der Pod-Spezifikation entfernen, stoppen aber, sobald die Debugging-Session endet. Kopierte Pods hingegen verbleiben im Cluster, bis sie gelöscht werden.

Halten Sie fest, was geprüft wurde, welche Befehle ausgeführt wurden und was dabei herauskam. Das erleichtert die Nachbereitung des Vorfalls und hilft, Runbooks für künftige Probleme zu verbessern.

Gute Notizen umfassen den betroffenen Pod oder Node, das verwendete Debug-Image, wichtige Befehlsausgaben und die letztendliche Ursache. So müssen andere Engineers dieselbe Untersuchung später nicht wiederholen.

Weniger manuelles Debugging: Resilienzrisiken proaktiv beheben mit PerfectScale

Befehle wie kubectl debug sind unverzichtbar, wenn Sie einen abstürzenden Pod, einen hängenden Prozess oder ein Problem auf Node-Ebene in Echtzeit untersuchen müssen – doch die meisten dieser Vorfälle gehen auf Ressourcen-Fehlkonfigurationen zurück, die sich früher hätten erkennen lassen. PerfectScale steigert die Resilienz und Performance von Kubernetes autonom: durch Right-Sizing der Workloads, die Vermeidung von Ausfällen und die Optimierung der Ressourcennutzung für 99,99 % Verfügbarkeit. So verbringt Ihr Team weniger Zeit mit interaktiven Debug-Sessions und mehr Zeit mit der Auslieferung neuer Features. Statt darauf zu warten, dass ein Pod ausfällt, und dann zu ephemeren Containern zu greifen, identifiziert und behebt PerfectScale die Resilienzrisiken, die diese Ausfälle überhaupt erst verursachen.

Zentrale Funktionen von PerfectScale:

• Automatische Problembehebung: Identifiziert und behebt Resilienzrisiken sofort, um die Verfügbarkeit zu maximieren und Latenzen zu eliminieren – und verhindert Konfigurationsfehler (fehlende CPU-Requests, fehlende Memory-Requests, fehlende Memory-Limits) sowie Unterversorgung mit Ressourcen wie OOM, CPU-Throttling und Evictions.
• Härtung der Infrastruktur: Verschafft Ihnen einen ganzheitlichen Überblick über Ihre Nodes, um Fehlkonfigurationen proaktiv aufzudecken, verhindert die Überbuchung von Nodes durch präzise Empfehlungen für Memory-Limits, validiert Node Affinities und Taints und wählt die am besten geeigneten Node-Typen für Ihre Pods.
• Priorisierung nach Auswirkung: Fokussiert Ihr Team in Echtzeit auf die kritischsten Probleme dank fortschrittlicher Auto-Priorisierung und richtet Alerts an Ihren SLAs und SLOs aus, damit die Service-Level im Zielbereich bleiben.
• Echtzeit-Alerts und Ticketing-Integrationen: Sendet sofortige Benachrichtigungen über Slack, MS Teams oder Datadog und lässt Sie jedes Problem mit nur einem Klick als Ticket in Ihren etablierten Workflow eskalieren.
• Breite Risikoabdeckung: Erkennt kontinuierlich Evictions, Out-of-Memory-Fehler, mutmaßliche Memory Leaks, CPU-Throttling, Pod-Neustarts, HPAs am Replica-Maximum sowie unterdimensionierte oder fehlende CPU- und Memory-Requests und -Limits.

Erfahren Sie mehr darüber, wie PerfectScale Ihre Cluster stabil hält und den Bedarf an manuellem Troubleshooting reduziert – auf der Plattform zur Kubernetes-Performance-Optimierung.

FAQ

Wofür wird der Befehl kubectl debug verwendet?

kubectl debug dient dem interaktiven Troubleshooting von Kubernetes-Workloads und -Nodes. Der Befehl kann einen ephemeren Container an einen laufenden Pod anhängen, eine modifizierte Kopie eines abstürzenden Pods erstellen oder einen Debug-Pod auf einem Node starten – ganz ohne Debugging-Tools, die bereits im Ziel-Image enthalten sein müssten.

Wie verwende ich kubectl debug bei einem Pod?

Führen Sie kubectl debug <pod-name> -it --image=busybox aus, um einen ephemeren Debug-Container an einen laufenden Pod anzuhängen. Ergänzen Sie --target=<container-name>, um den Prozess-Namespace mit einem bestimmten Container zu teilen, oder --copy-to=<new-pod-name>, um statt des Live-Pods eine Kopie zu debuggen (nützlich bei Pods, die beim Start abstürzen).

Wie verwende ich kubectl debug auf einem Node?

Führen Sie kubectl debug node/<node-name> -it --image=ubuntu aus, um einen Debug-Pod zu erstellen, der in den Host-Namespaces des Nodes läuft und dessen Root-Dateisystem unter /host gemountet hat. Standardmäßig gilt das Profil general, das keinen privilegierten Zugriff gewährt – nutzen Sie --profile=sysadmin, wenn Sie volle Root-Rechte benötigen.

Wie lautet die Syntax des Befehls kubectl debug?

Die allgemeine Form ist kubectl debug (POD | TYPE/NAME) [flags], am häufigsten verwendet mit --image zum Festlegen des Debug-Container-Images, -it für ein interaktives Terminal, --target zum Adressieren eines bestimmten Containers und --copy-to zum Debuggen einer Pod-Kopie.

Worin unterscheidet sich kubectl debug von kubectl exec?

kubectl exec führt einen Befehl innerhalb eines bestehenden Containers im eigenen Image des Pods aus und funktioniert daher nur, wenn dieses Image die benötigten Tools bereits enthält. kubectl debug hängt einen separaten Container (oder Pod) mit einem beliebigen Image Ihrer Wahl an – unverzichtbar bei minimalen oder Distroless-Containern, die gar keine Shell haben.

Verändert kubectl debug den ursprünglichen Pod oder seine Container?

Das Hinzufügen eines ephemeren Containers mit kubectl debug startet die bestehenden Container des Pods weder neu, noch verändert es sie – es wird lediglich ein temporärer Container daneben hinzugefügt. Mit --copy-to geht es noch einen Schritt weiter: Es wird ein separater Pod erstellt, sodass das Original völlig unangetastet bleibt.

Muss ich von kubectl debug erstellte Pods aufräumen?

Ja, bei jedem mit --copy-to erstellten Pod. Diese Pods verbleiben im Cluster, bis Sie sie mit kubectl delete pod <debug-pod-name> löschen. Ephemere Container, die direkt zu einem bestehenden Pod hinzugefügt wurden, benötigen keine separate Bereinigung – sie stoppen, wenn die Session endet, bleiben aber in der Pod-Spezifikation gelistet.