Debugging fehlgeschlagener Deployments: Identifizierung häufiger YAML- und Konfigurationsfehler

Fehler bei Kubernetes-Deployments zeigen sich normalerweise als Pods, die in Pending, ImagePullBackOff, CrashLoopBackOff stecken bleiben oder null verfügbare Replicas aufweisen. Die Ursache ist oft in Ereignissen sichtbar, aber Sie müssen das Deployment, das ReplicaSet und die Pods in der richtigen Reihenfolge inspizieren.

Diese Anleitung führt durch die Prüfungen, die normalerweise YAML-Fehler, Image-Pull-Probleme, fehlerhafte Probes, Ressourcenbeschränkungen und Scheduling-Regeln finden, die Ihr Deployment daran hindern, gesund zu werden.

Die ersten Schritte: Überprüfung des Deployment-Status und der Ereignisse

Wenn ein Deployment fehlschlägt, sollten Ihre ersten Diagnoseschritte immer die Überprüfung der primären Ressource selbst und der damit verbundenen Ereignisse ihrer verwalteten ReplicaSets und Pods umfassen. Dies bietet die höchste Sicht darauf, was Kubernetes zu tun versucht und warum es fehlschlägt.

1. Überprüfung der Deployment-Gesundheit

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

kubectl get deployments <deployment-name>

Wenn der Deployment-Status wenige oder null bereite Replicas anzeigt, fahren Sie mit der Überprüfung des ReplicaSets fort.

2. Überprüfung von ReplicaSet- und Pod-Ereignissen

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

kubectl describe rs <replicaset-name>

Untersuchen Sie entscheidend den Abschnitt Events am Ende der Ausgabe. Dieser Abschnitt detailliert kürzliche Aktionen, einschließlich Scheduling-Versuche, Image-Pull-Fehler und Probleme bei der Volume-Montage. Diese Ereignisse sind oft der entscheidende Hinweis.

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

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

Suchen Sie nach den Feldern State und Reason in der Pod-Beschreibung. 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 fehlgeschlagene Deployments. Diese Fehler können von einfachen Einrückungsfehlern bis zu komplexen strukturellen Problemen reichen.

1. YAML-Syntax- und Strukturfehler

Kubernetes-APIs sind extrem empfindlich gegenüber korrekter YAML-Syntax (Einrückung, Abstände und Datentypen). Wenn das YAML ungültig ist, wird kubectl apply oft sofort fehlschlagen und angeben, dass die Datei nicht geparst werden kann.

Best Practice: Verwenden Sie einen Linter Validieren Sie Ihre YAML-Syntax immer vor dem Anwenden. Tools wie yamllint oder integrierte IDE-Unterstützung können grundlegende Syntaxfehler sofort erkennen.

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

# FALSCH: containers gehört unter spec.template.spec, nicht direkt unter spec.template
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  template:
    metadata:
      labels:
        app: my-app
    containers:
      - name: my-app
        image: myregistry/myapp:v1

Richtige Platzierung:

spec:
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
        - name: my-app
          image: myregistry/myapp:v1
          ports:
            - containerPort: 8080

2. Image-Referenz- und Pull-Fehler

Wenn Pods in ImagePullBackOff oder ErrImagePull eintreten, liegt das Problem im Zugriff auf das Container-Image.

• Tippfehler im Image-Namen/Tag: Überprüfen Sie die Schreibweise des Image-Repository, -Namens und -Tags.
• Authentifizierung für private Registry: Wenn Sie von einer privaten Registry pullen, stellen Sie sicher, dass Sie ein Image-Pull-Secret erstellt und als imagePullSecrets in der Pod-Spezifikation referenziert haben.

# Ausschnitt, der die Verwendung von ImagePullSecret zeigt
spec:
  imagePullSecrets:
    - name: my-registry-secret
  containers:
    - name: my-app
      image: private.example.com/my-app:v1

3. Verstöße gegen Ressourcenanforderungen und -grenzen

Wenn ein Pod im Status Pending bleibt und die Ereignisse unzureichende Ressourcen erwähnen, können die Cluster-Knoten die im YAML definierten CPU- oder Speicheranforderungen nicht erfüllen.

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

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

Fehlerbehebungsschritte:

1. Verwenden Sie kubectl describe nodes, um die verfügbare Kapazität zu sehen.
2. Wenn Sie Ereignisse wie 0/3 nodes are available: 3 Insufficient cpu sehen, müssen Sie entweder die requests in Ihrem YAML senken oder weitere Knoten zum Cluster hinzufügen.

Fortgeschrittene Konfigurationsprobleme

Über grundlegende Syntax und Image-Pulls hinaus können komplexe Konfigurationen mit Netzwerk, Speicher und Scheduling zu schwer diagnostizierbaren Fehlern führen.

1. Fehlkonfigurierte Probes (Liveness und Readiness)

Wenn ein Pod in CrashLoopBackOff übergeht, bedeutet das oft, dass der Container startet, aber sofort einen Check nicht besteht, oder er startet, aber seinen Readiness-Probe wiederholt nicht besteht.

• Liveness-Probes: Wenn dieser wiederholt fehlschlägt, startet Kubernetes den Container neu. Überprüfen Sie kubectl describe pod <pod-name> auf Probe-Fehlerereignisse und kubectl logs <pod-name> --previous nach einem Neustart.
• Readiness-Probes: Wenn dieser fehlschlägt, läuft der Pod weiter, wird aber von den Service-Endpunkten ferngehalten. Stellen Sie sicher, dass der Pfad, der Port und der erwartete Antwortcode mit dem übereinstimmen, was Ihre Anwendung tatsächlich bereitstellt.

Beispiel für einen häufigen Readiness-Probe-Fehler: Zielen auf den falschen Port oder Erwarten von HTTP, wenn die App nur TCP bereitstellt.

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 das, 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 Scheduling-Regeln wie nodeAffinity oder podAntiAffinity können unbeabsichtigt verhindern, dass ein Pod geplant wird, wenn kein Knoten alle Kriterien erfüllt. Wenn Pods Pending bleiben und Ereignisse Scheduling-Einschränkungen erwähnen, überprüfen Sie diese Regeln.

Wenn Sie beispielsweise verlangen, dass ein Pod auf einem Knoten mit einem bestimmten Label (nodeSelector) läuft, das kein vorhandener Knoten besitzt, wird der Pod nie geplant.

# Beispiel: Einschränkung des Deployments auf Knoten mit dem Label 'disktype: ssd'
spec:
  nodeSelector:
    disktype: ssd
  containers:
  # ...

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

Debugging-Workflow

Wenn Sie mit einem fehlgeschlagenen Deployment konfrontiert sind, folgen Sie diesem strukturierten Pfad:

1. Deployment-Status: kubectl get deployments -> Melden Replicas sich bereit?
2. Pod-Ereignisse: kubectl describe pod <failing-pod> -> Überprüfen Sie den Abschnitt Events auf sofortige Fehler (ImagePull, OOMKilled, Volume-Probleme).
3. Container-Logs: kubectl logs <failing-pod> -> Wenn der Container startet, aber abstürzt (CrashLoopBackOff), sind Anwendungslogik oder Liveness-Probes verdächtig.
4. Ressourcenprüfung: Wenn der Pod Pending ist, überprüfen Sie auf Ressourcenbeschränkungen (Insufficient cpu/memory) oder fehlgeschlagene Volume-Bindungen (PVC-Status).
5. Konfigurationsvalidierung: Überprüfen Sie das YAML auf Einrückung, korrekte Feldnamen und gültige Ressourcenwerte (requests/limits).

Arbeiten Sie basierend auf den Beweisen des Clusters, anstatt zu raten. Überprüfen Sie Status, Ereignisse, Logs, Ressourcen und Manifeststruktur in dieser Reihenfolge und nehmen Sie dann die kleinste YAML-Änderung vor, die dem gefundenen Fehler entspricht.