Fehlerbehebung bei fehlgeschlagenen Bereitstellungen: Häufige YAML- und Konfigurationsfehler identifizieren

Das Bereitstellen von Anwendungen in Kubernetes wird oft durch deklarative Konfiguration, die über YAML-Manifeste verwaltet wird, optimiert. Wenn Bereitstellungen jedoch den gewünschten Zustand nicht erreichen – im Status Pending oder ImagePullBackOff stecken bleiben oder abrupt fehlschlagen –, liegt die Ursache häufig in einem subtilen Fehler in diesen Konfigurationsdateien oder den zugrunde liegenden Clusterressourcen. Dieser Leitfaden bietet einen systematischen Ansatz zur Diagnose und Behebung häufiger YAML- und Konfigurationsprobleme, die Kubernetes-Bereitstellungen plagen.

Das Verständnis, wie Kubernetes-Ereignisse zu interpretieren und der Ressourcenstatus zu überprüfen ist, ist entscheidend für eine effiziente Fehlerbehebung. Dieser Artikel führt Sie durch die wesentlichen Befehle und Prüfungen, die erforderlich sind, um Ihre fehlschlagenden Bereitstellungen schnell in einen gesunden, laufenden Zustand zu versetzen, wobei der Schwerpunkt auf Syntaxfehlern, Ressourcenbeschränkungen und Problemen bei der Netzwerkkonfiguration liegt.

Die ersten Schritte: Überprüfung des Bereitstellungsstatus und der Ereignisse

Wenn eine Bereitstellung fehlschlägt, sollten Ihre ersten Diagnoseschritte immer die Überprüfung der primären Ressource selbst und der Ereignisse, die mit ihren verwalteten ReplicaSets und Pods verbunden sind, umfassen. Dies bietet die umfassendste Ansicht dessen, was Kubernetes versucht zu tun und warum es fehlschlägt.

1. Überprüfung des Bereitstellungszustands

Verwenden Sie kubectl get deployments, um den Gesamtstatus anzuzeigen. Achten Sie besonders auf die Spalten READY, UP-TO-DATE und AVAILABLE. Eine Diskrepanz hier weist auf ein Problem mit den zugrunde liegenden Pods hin.

kubectl get deployments <deployment-name>

Wenn der Bereitstellungsstatus nur wenige oder keine bereiten Replikate anzeigt, fahren Sie mit der Überprüfung des ReplicaSets fort.

2. Überprüfung der ReplicaSet- und Pod-Ereignisse

ReplicaSets verwalten die gewünschte Anzahl von Pods. Wenn die Bereitstellung fehlschlägt, ist das ReplicaSet normalerweise die Quelle der Fehlerkaskade. Verwenden Sie den Befehl describe für das ReplicaSet, das normalerweise <deployment-name>-<hash> benannt ist:

kubectl describe rs <replicaset-name>

Prüfen Sie insbesondere den Abschnitt Events am Ende der Ausgabe. Dieser Abschnitt beschreibt die letzten Aktionen, einschließlich Planungsversuchen, Fehlern beim Abrufen von Images und Problemen beim Einhängen von Volumes. Diese Ereignisse sind oft der entscheidende Hinweis.

Überprüfen Sie abschließend die Pods selbst, da sie den unmittelbaren Fehler melden:

kubectl get pods -l app=<your-app-label>
kubectl describe pod <pod-name>

Suchen Sie in der Pod-Beschreibung nach den Feldern State und Reason. Häufige Gründe sind ImagePullBackOff, ErrImagePull, CrashLoopBackOff und Pending.

Häufige Konfigurationsfehler in YAML-Manifesten

Fehlkonfigurationen in Ihren YAML-Dateien sind die häufigste Ursache für Bereitstellungsfehler. Diese Fehler können von einfachen Einrückungsfehlern bis hin zu komplexen strukturellen Problemen reichen.

1. YAML-Syntax- und Strukturfehler

Kubernetes-APIs sind äußerst empfindlich gegenüber korrekter YAML-Syntax (Einrückung, Abstände und Datentypen). Wenn die YAML-Datei ungültig ist, schlägt kubectl apply oft sofort fehl und gibt an, dass die Datei nicht geparst werden kann.

Best Practice: Verwenden Sie einen Linter
Validieren Sie immer Ihre YAML-Syntax, bevor Sie sie anwenden. Tools wie yamllint oder die integrierte IDE-Unterstützung können grundlegende Syntaxfehler sofort erkennen.

Beispiel für einen häufigen strukturellen Fehler: Falsche Zuordnung oder Einrückung.

# FALSCHE Einrückung für den Container-Port
containers:
  - name: my-app
    image: myregistry/myapp:v1
    ports:
    - containerPort: 8080  # Sollte unter dem Listeneintrag '-' eingerückt sein

2. Image-Referenz- und Pull-Fehler

Wenn Pods in den Status ImagePullBackOff oder ErrImagePull wechseln, hängt das Problem mit dem Zugriff auf das Container-Image zusammen.

• Tippfehler im Image-Namen/Tag: Überprüfen Sie die Schreibweise des Image-Repositorys, Namens und Tags.
• Authentifizierung bei privatem Registry: Wenn Sie von einem privaten Registry (wie privaten Docker Hub-Repositorys oder ECR/GCR) ziehen, stellen Sie sicher, dass Sie ein ImagePullSecret in der Pod-Spezifikation korrekt konfiguriert und referenziert haben.

# Snippet zur Verwendung von ImagePullSecret
spec:
  imagePullSecrets:
  - name: my-registry-secret
  containers:
  # ... Rest der Container-Spezifikation

3. Verletzungen von Ressourcenanforderungen und -limits

Bleibt ein Pod im Status Pending und erwähnen die Ereignisse unzureichende Ressourcen, können die Cluster-Nodes die in der YAML-Datei definierten CPU- oder Speicheranforderungen nicht erfüllen.

Überprüfen Sie die in Ihrem Deployment-Manifest angegebenen Limits:

resources:
  requests:
    memory: "512Mi"
    cpu: "500m"
  limits:
    memory: "1Gi"
    cpu: "1"

Fehlerbehebungsschritte:
1. Verwenden Sie kubectl describe nodes, um die verfügbare Kapazität anzuzeigen.
2. Wenn Sie Ereignisse wie 0/3 nodes are available: 3 Insufficient cpu sehen, müssen Sie entweder die requests in Ihrer YAML-Datei senken oder dem Cluster weitere Nodes hinzufügen.

Erweiterte Konfigurationsprobleme

Neben grundlegenden Syntax- und Image-Pull-Problemen können komplexe Konfigurationen, die Netzwerke, Speicher und Scheduling betreffen, zu schwer zu diagnostizierenden Fehlern führen.

1. Falsch konfigurierte Probes (Liveness und Readiness)

Wenn ein Pod in den Status CrashLoopBackOff übergeht, bedeutet dies oft, dass der Container startet, aber sofort einen Check fehlschlägt, oder er startet, aber seine Readiness-Probe wiederholt fehlschlägt.

• Liveness Probes: Wenn diese fehlschlägt, startet Kubernetes den Container neu. Überprüfen Sie die Anwendungsprotokolle (kubectl logs <pod-name>), um zu sehen, warum er abstürzt.
• Readiness Probes: Wenn diese fehlschlägt, wird der Pod aus den Service-Endpoints herausgehalten. Stellen Sie sicher, dass Pfad, Port und erwarteter Antwortcode mit dem übereinstimmen, was Ihre Anwendung tatsächlich bereitstellt.

Beispiel für einen häufigen Readiness Probe-Fehler: Das Anzielen des falschen Ports oder das Erwarten von HTTP, wenn die App nur TCP exponiert.

2. Volume- und PersistentVolumeClaim (PVC)-Fehler

Wenn Pods aufgrund von Volume-Problemen ausstehen, überprüfen Sie den PVC-Status:

kubectl get pvc <pvc-name>

Wenn der PVC-Status Pending ist, bedeutet dies, dass der Cluster keine passende StorageClass oder ein geeignetes PersistentVolume zum Binden finden konnte. Überprüfen Sie die PVC-Ereignisse auf spezifische Bindungsfehler.

3. Affinitäts- und Anti-Affinitätsregeln

Komplexe Planungsregeln, wie nodeAffinity oder podAntiAffinity, können unbeabsichtigt verhindern, dass ein Pod geplant wird, wenn kein Node alle Kriterien erfüllt. Wenn Pods Pending bleiben und Ereignisse Planungsbeschränkungen erwähnen, überprüfen Sie diese Regeln.

Wenn Sie beispielsweise einen Pod auf einem Node mit einem bestimmten Label (nodeSelector) ausführen möchten, den kein vorhandener Node besitzt, wird der Pod niemals geplant.

# Beispiel: Einschränkung der Bereitstellung auf Nodes mit dem Label 'disktype: ssd'
spec:
  nodeSelector:
    disktype: ssd
  containers:
  # ...

Fehlerbehebungstipp: Kommentieren Sie restriktive nodeSelector- oder affinity-Regeln vorübergehend aus. Wenn der Pod erfolgreich geplant wird, wissen Sie, dass das Problem in den Auswahlkriterien liegt.

Zusammenfassung des Debugging-Workflows

Wenn Sie mit einer fehlgeschlagenen Bereitstellung konfrontiert sind, folgen Sie diesem strukturierten Pfad:

1. Bereitstellungsstatus: kubectl get deployments -> Melden Replikate, dass sie bereit sind?
2. Pod-Ereignisse: kubectl describe pod <failing-pod> -> Überprüfen Sie den Abschnitt Events auf unmittelbare Fehler (ImagePull, OOMKilled, Volume-Probleme).
3. Container-Protokolle: kubectl logs <failing-pod> -> Wenn der Container startet, aber abstürzt (CrashLoopBackOff), sind die Anwendungslogik oder Liveness-Probes verdächtig.
4. Ressourcenprüfung: Wenn der Pod Pending ist, suchen Sie nach Ressourcenengpässen (Insufficient cpu/memory) oder fehlgeschlagenen Volume-Bindungen (PVC-Status).
5. Konfigurationsvalidierung: Überprüfen Sie die YAML-Datei auf Einrückungen, korrekte Feldnamen und gültige Ressourcenwerte (Requests/Limits).

Durch die systematische Überprüfung des Status, der Ereignisse und der zugrunde liegenden YAML-Konfiguration anhand der Kubernetes-Erwartungen können Sie die Ursache der meisten Bereitstellungsfehler schnell isolieren und beheben.