Kubernetes-Troubleshooting: Fehler schnell finden und beheben

TLDR:
Kubernetes-Troubleshooting funktioniert von unten nach oben: Pod-Status prüfen, Events untersuchen, Logs ansehen und bei Bedarf interaktiv debuggen. Die meisten Probleme lassen sich auf eine Handvoll wiederkehrender Fehler zurückführen (ImagePullBackOff, CrashLoopBackOff, Pending, OOMKilled), die sich jeweils mit kubectl describe/logs nachvollziehen lassen. Wiederkehrenden Problemen beugen Sie vor, indem Sie passende Resource Requests und Limits setzen, Probes sorgfältig konfigurieren, kontinuierlich überwachen und Ihre Workloads im Laufe der Zeit per Right-Sizing anpassen.

Häufige Kubernetes-Fehlercodes und ihre Lösungen

ImagePullBackOff

Problem: ImagePullBackOff tritt auf, wenn Kubernetes ein Container-Image nicht abrufen kann, das für den Start eines Pods erforderlich ist. Nach dem ersten fehlgeschlagenen Image-Pull wiederholt Kubernetes den Vorgang mit zunehmend längeren Wartezeiten. Bis das Image verfügbar ist, bleibt der Pod in einem nicht lauffähigen Zustand.

Diagnose: Fehlgeschlagene Image-Pulls werden meist durch ungültige Image-Namen, falsche Tags, fehlende Registry-Credentials, abgelaufene Authentifizierungs-Tokens, Registry-Ausfälle oder Netzwerkprobleme verursacht. Der beste Ausgangspunkt ist der Events-Abschnitt der Pod-Beschreibung.

Führen Sie kubectl describe pod <pod-name> aus und achten Sie auf Meldungen wie ErrImagePull, pull access denied, unauthorized oder manifest unknown. Diese Meldungen zeigen in der Regel, ob der Fehler mit Authentifizierung, Image-Verfügbarkeit oder Konnektivität zusammenhängt.

Lösungsworkflow:

1. Führen Sie kubectl describe pod <pod-name> aus und prüfen Sie den Events-Abschnitt.
2. Verifizieren Sie, dass Image-Name und Tag korrekt sind und in der Registry existieren.
3. Stellen Sie sicher, dass die Container-Registry von den Cluster-Nodes aus erreichbar ist.
4. Validieren Sie die Image Pull Secrets, die für den Pod oder Service Account konfiguriert sind.
5. Prüfen Sie Registry-Credentials, Berechtigungen und den Ablaufstatus von Tokens.
6. Verifizieren Sie DNS-Auflösung und ausgehende Netzwerkkonnektivität der Worker Nodes.
7. Prüfen Sie Proxy-, Firewall- oder Network-Policy-Konfigurationen, die den Registry-Zugriff blockieren könnten.

Beispiel

kubectl describe pod my-pod
kubectl get secrets
kubectl describe secret registry-secret

CrashLoopBackOff

Problem: CrashLoopBackOff bedeutet, dass ein Container wiederholt startet, sich beendet und von Kubernetes neu gestartet wird. Nach mehreren aufeinanderfolgenden Fehlern verlängert Kubernetes die Pausen zwischen den Neustartversuchen, um ständige Restart-Zyklen zu vermeiden.

Diagnose: Dieser Zustand wird typischerweise durch fehlgeschlagene Anwendungsstarts, ungültige Konfigurationswerte, fehlende Umgebungsvariablen, gescheiterte Initialisierung von Abhängigkeiten, Probleme mit der Datenbankverbindung oder falsche Container-Befehle verursacht.

Container-Logs sind meist der schnellste Weg zur Ursache. Prüfen Sie die Logs mit kubectl logs <pod-name>. Startet der Container zu schnell neu, nutzen Sie das Flag --previous, um die Logs der letzten fehlgeschlagenen Instanz abzurufen. Auch die Pod-Beschreibung kann Beendigungsgründe, Exit-Codes, Restart-Zähler und Probe-Fehler offenlegen.

Lösungsworkflow:

1. Prüfen Sie die Anwendungslogs mit kubectl logs <pod-name>.
2. Rufen Sie bei Bedarf die Logs der vorherigen Container-Instanz mit --previous ab.
3. Untersuchen Sie Pod-Events und Beendigungsdetails mit kubectl describe pod <pod-name>.
4. Verifizieren Sie Umgebungsvariablen, Konfigurationsdateien, Secrets und Startbefehle.
5. Prüfen Sie Datenbankverbindungen, externe Abhängigkeiten und Service-Endpoints.
6. Prüfen Sie CPU- und Speicherlimits auf Anzeichen von Ressourcenerschöpfung.
7. Validieren Sie die Einstellungen der Readiness-, Startup- und Liveness-Probes und passen Sie die Zeitvorgaben bei Bedarf an.

Beispiel

kubectl logs my-pod
kubectl logs my-pod --previous
kubectl describe pod my-pod

Pending

Problem: Ein Pod befindet sich im Zustand Pending, wenn Kubernetes die Pod-Definition akzeptiert, ihn aber keinem geeigneten Node zuweisen kann. Der Workload wird nicht eingeplant und startet erst, wenn alle Scheduling-Anforderungen erfüllt sind.

Diagnose: Pending-Pods entstehen meist durch unzureichende Cluster-Ressourcen, restriktive Scheduling-Regeln, fehlgeschlagene Storage-Bereitstellung oder Einschränkungen bei der Node-Platzierung. Häufige Scheduling-Meldungen sind unzureichende CPU, unzureichender Speicher, nicht passende Node-Selektoren, Taint-Konflikte oder nicht gebundene PersistentVolumeClaims.

Die von kubectl describe pod <pod-name> angezeigten Scheduling-Events benennen in der Regel den genauen Grund, warum der Scheduler den Workload nicht platzieren konnte.

Lösungsworkflow:

1. Führen Sie kubectl describe pod <pod-name> aus und prüfen Sie die Scheduler-Events.
2. Prüfen Sie die Node-Verfügbarkeit mit kubectl get nodes.
3. Verifizieren Sie, dass ausreichend CPU- und Speicherressourcen im Cluster vorhanden sind.
4. Prüfen Sie Node-Selektoren, Node-Affinity-Regeln, Taints und Tolerations.
5. Validieren Sie, dass die erforderlichen Node-Labels vorhanden sind.
6. Prüfen Sie PersistentVolumeClaims (PVC) und den Status der Storage-Bereitstellung.
7. Falls Autoscaling aktiviert ist, stellen Sie sicher, dass der Cluster Autoscaler korrekt funktioniert.

Beispiel

kubectl describe pod my-pod
kubectl get nodes
kubectl get pvc

OOMKilled

Problem: OOMKilled tritt auf, wenn ein Container sein konfiguriertes Speicherlimit überschreitet und vom Linux-Out-of-Memory-Killer (OOM-Killer) beendet wird. Kubernetes setzt Speicherlimits strikt durch: Der Container wird sofort gestoppt, sobald das Limit überschritten wird.

Diagnose: Speichererschöpfung kann durch Memory Leaks, exzessives Caching, ineffizientes Anwendungsverhalten, Traffic-Spitzen, große Datenmengen oder zu niedrig angesetzte Speicherlimits für den Workload entstehen.

Die Pod-Beschreibung zeigt in der Regel OOMKilled als Beendigungsgrund. Monitoring-Tools wie Prometheus, Grafana oder der Metrics Server helfen festzustellen, ob der Workload unter anhaltendem Speicherdruck steht oder plötzliche Nutzungsspitzen auftreten.

Lösungsworkflow:

1. Bestätigen Sie den Beendigungsgrund mit kubectl describe pod <pod-name>.
2. Prüfen Sie die Metriken zum Speicherverbrauch vor dem Ausfall.
3. Identifizieren Sie Speicherspitzen, Leaks oder anhaltend hohe Auslastung.
4. Vergleichen Sie den tatsächlichen Speicherverbrauch mit den konfigurierten Requests und Limits.
5. Erhöhen Sie die Speicherlimits, wenn sie offensichtlich zu knapp bemessen sind.
6. Untersuchen Sie Ursachen auf Anwendungsebene wie Caching, Concurrency oder Memory Leaks.
7. Optimieren Sie den Speicherverbrauch der Anwendung und passen Sie die Ressourceneinstellungen basierend auf dem beobachteten Workload-Verhalten an.

Beispiel

kubectl describe pod my-pod
kubectl top pod my-pod
kubectl top nodes

5 Wege, Kubernetes-Probleme von vornherein zu vermeiden

Erfahrene Kubernetes-Teams planen ihre Cluster so, dass typische Fehler von Anfang an minimiert werden. Das stärkt die Resilienz und erleichtert das Troubleshooting, wenn doch einmal Probleme auftreten.

1. Resource Requests und Limits setzen

Resource Requests und Limits helfen Kubernetes, CPU und Speicher vorhersehbar im Cluster zu verteilen. Requests definieren die für das Scheduling erforderlichen Mindestressourcen, Limits legen fest, wie viele Ressourcen ein Container maximal verbrauchen darf. Eine saubere Konfiguration verhindert, dass Workloads aggressiv um gemeinsam genutzte Ressourcen konkurrieren.

Ohne Requests kann der Scheduler keine fundierten Platzierungsentscheidungen treffen – das führt zu überlasteten Nodes und instabilen Workloads. Ohne Limits kann ein einzelner Container übermäßig viel Speicher oder CPU verbrauchen und andere Anwendungen auf demselben Node beeinträchtigen.

Sorgfältig konfigurierte Limits reduzieren das Risiko von OOMKilled-Events, CPU-Throttling und Ressourcenerschöpfung auf Node-Ebene. Zu niedrig angesetzte Limits können jedoch ebenfalls Instabilität erzeugen, weil sie Anwendungen in Lastspitzen ausbremsen.

LimitRange- und ResourceQuota-Richtlinien auf Namespace-Ebene helfen, ein konsistentes Ressourcenmanagement über Teams und Umgebungen hinweg durchzusetzen. Diese Kontrollen verringern die Wahrscheinlichkeit, dass fehlkonfigurierte Workloads die Cluster-Stabilität gefährden.

2. Readiness- und Liveness-Probes mit Bedacht einsetzen

Readiness- und Liveness-Probes helfen Kubernetes zu erkennen, ob Container gesund und bereit sind, Traffic zu empfangen. Eine sorgfältige Probe-Konfiguration verbessert die Zuverlässigkeit von Anwendungen: Sie verhindert, dass fehlerhafte Pods Anfragen bedienen, und startet fehlgeschlagene Container automatisch neu.

Readiness-Probes steuern, ob ein Pod in die Endpoint-Liste eines Service aufgenommen wird. Schlägt die Readiness-Probe fehl, wird kein Traffic mehr an den Pod geroutet, bis er sich erholt hat. So erreichen Nutzer keine nur teilweise initialisierten oder beeinträchtigten Anwendungen.

Liveness-Probes erkennen Deadlocks oder nicht mehr reagierende Prozesse. Schlägt eine Liveness-Probe wiederholt fehl, startet Kubernetes den Container automatisch neu. Dieser Mechanismus verbessert das Self-Healing, kann bei falscher Konfiguration aber auch Instabilität verursachen.

Zu aggressiv getaktete Probes sind eine häufige Ursache für unnötige Restarts und CrashLoopBackOff-Zustände. Anwendungen mit langen Startzeiten können an Health Checks scheitern, bevor die Initialisierung abgeschlossen ist. Für Workloads mit langsamen Boot-Prozessen sind Startup-Probes oft die richtige Wahl.

3. Events, Logs und Metriken überwachen

Kontinuierliches Monitoring ist entscheidend, um Kubernetes-Probleme zu erkennen, bevor sie zu Ausfällen eskalieren. Logs, Metriken und Cluster-Events geben Einblick in Workload-Verhalten, Ressourcennutzung, Infrastruktur-Zustand und operative Fehler.

Metrik-Plattformen wie Prometheus und Grafana helfen, CPU-Auslastung, Speicherverbrauch, Pod-Restarts, Netzwerklatenz und Storage-Performance zu verfolgen. Wer Trends über die Zeit beobachtet, erkennt abnormales Verhalten, bevor Services instabil werden.

Zentralisierte Logging-Systeme verbessern das Troubleshooting, indem sie Container-Logs, Node-Logs und System-Events in einer durchsuchbaren Plattform bündeln. Tools wie Elasticsearch, Fluent Bit, Loki und Splunk werden häufig für die Sammlung und Analyse von Kubernetes-Logs eingesetzt.

Kubernetes-Events liefern zusätzlichen operativen Kontext, indem sie Scheduling-Fehler, Image-Pull-Fehler, Pod-Evictions und Konfigurationsprobleme protokollieren. Da Events flüchtig sind, verbessert das externe Sammeln und Speichern die langfristigen Troubleshooting-Möglichkeiten.

4. Namespaces und Labels konsequent nutzen

Namespaces helfen, Workloads zu organisieren und Ressourcen innerhalb eines Kubernetes-Clusters zu isolieren. Eine konsequente Namespace-Nutzung verbessert operative Übersicht, Zugriffskontrolle, Ressourcenmanagement und Troubleshooting-Effizienz.

Die Trennung von Umgebungen wie Development, Staging und Production in verschiedene Namespaces reduziert das Risiko unbeabsichtigter Wechselwirkungen zwischen Workloads. Richtlinien auf Namespace-Ebene können zudem Sicherheitsgrenzen und Resource Quotas durchsetzen.

Labels liefern Metadaten für Workload-Auswahl, Gruppierung, Monitoring und Automatisierung. Kubernetes-Services, Deployments, Network Policies und Monitoring-Systeme sind für die Identifikation von Workloads stark auf Labels angewiesen.

Inkonsistente oder schlecht durchdachte Labeling-Schemata verursachen häufig fehlerhaftes Service-Routing, Verwirrung bei Deployments und operative Komplexität. Standardisierte Labels erleichtern das Suchen, Überwachen und Verwalten von Workloads in großen Clustern.

5. Workloads kontinuierlich auf Basis realer Nutzung per Right-Sizing anpassen

Der Ressourcenbedarf von Workloads verändert sich mit der Zeit – Anwendungen entwickeln sich weiter, Traffic-Muster verschieben sich, die Infrastrukturnutzung wächst. Kontinuierliches Right-Sizing hält die Performance stabil und reduziert gleichzeitig verschwendete Cluster-Ressourcen.

Überprovisionierte Workloads verschwenden CPU und Speicher, treiben die Infrastrukturkosten in die Höhe und senken die Cluster-Effizienz. Unterprovisionierte Workloads verursachen Instabilität, Scheduling-Fehler, CPU-Throttling und speicherbedingte Abstürze.

Das Monitoring des tatsächlichen Workload-Verhaltens liefert die Daten, die zur Optimierung von Resource Requests und Limits nötig sind. Engineers sollten langfristige Nutzungsmuster auswerten, statt sich nur auf kurzfristige Spitzen oder anfängliche Deployment-Schätzungen zu verlassen.

Tools wie der Vertical Pod Autoscaler (VPA) können Ressourceneinstellungen auf Basis des beobachteten Verbrauchs empfehlen oder automatisch anpassen. Der Horizontal Pod Autoscaler (HPA) ergänzt diesen Ansatz, indem er die Replica-Anzahl an Laständerungen anpasst.

Wie PerfectScale Ihnen hilft, Kubernetes-Probleme zu vermeiden und zu beheben

Das meiste Kubernetes-Troubleshooting ist reaktiv: Man wartet, bis ein Pod abstürzt, und wühlt sich dann durch Events, Logs und Metriken, um die Ursache zu finden. PerfectScale dreht dieses Modell um – durch autonomes Right-Sizing von Workloads, die Vermeidung von Ausfallzeiten und die Optimierung der Ressourcennutzung für 99,99 % Verfügbarkeit. Statt OOMKilled, CrashLoopBackOff und Throttling-Events manuell hinterherzujagen, erhalten Ihre DevOps-, SRE- und Platform-Engineering-Teams kontinuierliche, datengetriebene Fehlerbehebung über alle Ebenen des K8s-Stacks hinweg.

Die wichtigsten Funktionen von PerfectScale:

• Automatische Problembehebung: Erkennen und beheben Sie Resilienz-Risiken sofort, um die Uptime zu maximieren und Latenzen zu eliminieren – Probleme wie OOM, CPU-Throttling und Pod-Evictions werden adressiert, bevor sie zu Ausfällen eskalieren.
• Vermeidung von Konfigurationsfehlern: Fangen Sie die Fehlkonfigurationen hinter typischen Fehlern ab – fehlende CPU-Requests, fehlende Memory-Requests und nicht gesetzte Memory-Limits –, damit Workloads zuverlässig starten und laufen.
• Erkennung von Under-Provisioning: Machen Sie unterprovisionierte CPU und Speicher (Requests wie Limits) und mutmaßliche Memory Leaks sichtbar – die Ursachen, die Pods in Restart-Schleifen festhalten, selbst wenn die Nodes gesund aussehen.
• Härtung der Infrastruktur: Verschaffen Sie sich ganzheitliche Sichtbarkeit über alle Nodes, um Node-Overcommitment zu verhindern, Node Affinities und Taints zu validieren und die optimalen Node-Typen für Ihre Workloads zu wählen.
• Priorisierung nach Auswirkung: Richten Sie das Alerting an Ihren SLAs und SLOs aus, erhalten Sie sofortige Benachrichtigungen über Slack, MS Teams oder Datadog und eskalieren Sie Probleme mit einem Klick in ein Ticket.
• Autoscaling-Optimierung: Justieren Sie horizontale und vertikale Autoscaling-Konfigurationen so präzise, dass Skalierungs-Trigger zuverlässig auslösen – und verhindern Sie Szenarien wie "HPA am Replica-Maximum" oder Ressourcenerschöpfung, die Instabilität verursachen.

FAQ

Welchen Befehl führe ich als Erstes aus, wenn ein Pod Probleme hat? kubectl get pods, um den fehlerhaften Pod zu identifizieren, dann kubectl describe pod <pod-name> für Details zu seinem Zustand und den letzten Events.

Was verursacht CrashLoopBackOff? Der Container startet, beendet sich und startet wiederholt neu – meist durch einen fehlgeschlagenen Anwendungsstart, fehlerhafte Konfiguration, fehlende Umgebungsvariablen oder einen Verbindungsfehler zu Datenbank oder Abhängigkeiten. Prüfen Sie zuerst kubectl logs <pod-name> --previous.

Was verursacht ImagePullBackOff? Kubernetes kann das Container-Image nicht abrufen – häufig wegen eines ungültigen Image-Namens/Tags, fehlender oder abgelaufener Registry-Credentials oder eines Netzwerkproblems beim Zugriff auf die Registry.

Warum hängt mein Pod im Zustand Pending? Der Scheduler kann ihn nicht platzieren – typischerweise wegen unzureichender CPU/Speicher im Cluster, nicht passender Node-Selektoren oder Taints oder eines nicht gebundenen PersistentVolumeClaim. kubectl describe pod <pod-name> zeigt den genauen Scheduling-Grund.

Was bedeutet OOMKilled? Der Container hat sein Speicherlimit überschritten und wurde vom Linux-OOM-Killer beendet. Vergleichen Sie den Speicherverbrauch mit den konfigurierten Requests/Limits und suchen Sie nach Leaks oder zu knapp bemessenen Limits.

Wie debugge ich Netzwerk- oder DNS-Probleme? Mit kubectl get endpoints prüfen Sie, ob Pods einem Service zugeordnet sind, und mit kubectl exec -it <pod-name> -- nslookup <service-name> testen Sie die DNS-Auflösung aus einem Pod heraus.

Wie kann ich solche Probleme verhindern, statt nur darauf zu reagieren? Setzen Sie passende Resource Requests/Limits, konfigurieren Sie Readiness-/Liveness-Probes sorgfältig, überwachen Sie Logs/Events/Metriken kontinuierlich, nutzen Sie konsistente Namespaces und Labels und passen Sie Workloads im Laufe der Zeit per Right-Sizing an (z. B. mit VPA/HPA oder einem Tool wie PerfectScale).

Genug vom permanenten Feuerlöschen bei Kubernetes-Problemen? Entdecken Sie die Kubernetes-Performance- und Resilienz-Plattform von PerfectScale und erleben Sie, wie autonome Optimierung Ihre Cluster stabil, resilient und kosteneffizient hält.