Kubernetes Pod Terminating hängt: Force Delete und Finalizer Fix

TL;DR

Pod hängt in Terminating? Erst kubectl delete pod <name> --grace-period=0 --force versuchen. Hilft das nicht, hat der Pod einen Finalizer -- den entfernen Sie per kubectl patch. Bevor Sie blind force-deleten: prüfen Sie mit kubectl describe, warum der Pod hängt.

Der schnelle Fix: Force Delete

Wenn ein Pod seit Minuten im Status Terminating feststeckt, ist das der erste Befehl:

# Force Delete mit Grace Period 0
kubectl delete pod my-stuck-pod -n default --grace-period=0 --force

In ca. 70% der Fälle reicht das. Der Pod verschwindet aus der API, auch wenn der Container auf dem Node noch läuft. Kubernetes räumt den Container im Hintergrund auf.

Falls der Pod danach immer noch da ist, liegt es fast immer an einem Finalizer.

Warum Pods in Terminating hängenbleiben

Drei Ursachen decken 95% aller Fälle ab:

Den Status prüfen

# Pod-Details anzeigen -- achten Sie auf die Finalizer-Sektion
kubectl get pod my-stuck-pod -n default -o yaml | grep -A 5 finalizers

# Events des Pods prüfen
kubectl describe pod my-stuck-pod -n default | tail -20

Die Ausgabe zeigt Ihnen sofort, ob ein Finalizer hängt:

metadata:
  finalizers:
  - kubernetes.io/pv-protection
  - some-custom-finalizer.io/cleanup
  deletionTimestamp: "2026-03-08T14:32:00Z"

Wenn deletionTimestamp gesetzt ist und finalizers nicht leer -- dann blockiert der Finalizer das Löschen.

Finalizer entfernen: Der richtige Weg

Finalizer existieren aus gutem Grund. Sie stellen sicher, dass externe Ressourcen (Storage, Load Balancer, DNS-Einträge) aufgeräumt werden, bevor ein Objekt verschwindet. Blind entfernen kann zu verwaisten Ressourcen führen.

Trotzdem, wenn der zugehörige Controller nicht mehr läuft oder defekt ist, müssen Sie den Finalizer manuell entfernen:

# Finalizer per JSON Patch entfernen
kubectl patch pod my-stuck-pod -n default -p '{"metadata":{"finalizers":null}}' --type=merge

Der Pod sollte innerhalb von Sekunden verschwinden.

Einzelnen Finalizer entfernen statt alle

Wenn mehrere Finalizer gesetzt sind und Sie nur einen bestimmten entfernen wollen:

# Nur einen spezifischen Finalizer entfernen per JSON Patch
kubectl patch pod my-stuck-pod -n default --type=json \
  -p='[{"op": "remove", "path": "/metadata/finalizers/0"}]'

Der Index 0 entfernt den ersten Finalizer in der Liste. Passen Sie den Index entsprechend an.

Sonderfall: Node ist NotReady

Wenn der Node, auf dem der Pod läuft, nicht erreichbar ist, kann das Kubelet den Container nicht stoppen. Der Pod bleibt in Terminating, weil die API auf die Bestätigung vom Kubelet wartet.

# Prüfen, auf welchem Node der Pod läuft
kubectl get pod my-stuck-pod -n default -o wide

# Node-Status prüfen
kubectl get nodes

Ihre Optionen bei einem NotReady-Node:

1. Node reparieren -- SSH auf den Node, systemctl restart kubelet
2. Force Delete -- kubectl delete pod --grace-period=0 --force
3. Node aus dem Cluster entfernen -- kubectl delete node <node-name> (Vorsicht: alle Pods auf dem Node werden neu gescheduled)

Viele Pods gleichzeitig in Terminating

Manchmal hängen nach einem fehlgeschlagenen Rollout dutzende Pods. Einzeln löschen ist keine Option:

# Alle Terminating-Pods in einem Namespace force-deleten
kubectl get pods -n my-namespace --field-selector=status.phase=Failed -o name | \
  xargs kubectl delete -n my-namespace --grace-period=0 --force

# Alternative: Alle Pods mit Status Terminating finden und löschen
kubectl get pods -n my-namespace | grep Terminating | awk '{print $1}' | \
  xargs kubectl delete pod -n my-namespace --grace-period=0 --force

Präventive Maßnahmen

Damit Pods gar nicht erst in Terminating hängenbleiben:

• PreStop Hooks testen: Ein fehlerhafter PreStop Hook kann den Shutdown blockieren. Testen Sie, ob Ihr Container auf SIGTERM korrekt reagiert.
• terminationGracePeriodSeconds anpassen: Der Default ist 30 Sekunden. Für Pods mit langen Shutdown-Prozessen erhöhen, für stateless Pods auf 5-10 Sekunden reduzieren.
• Finalizer-Controller überwachen: Wenn Sie Custom Finalizer nutzen, muss der zugehörige Controller zuverlässig laufen.

spec:
  terminationGracePeriodSeconds: 10  # Schnellerer Shutdown
  containers:
  - name: app
    lifecycle:
      preStop:
        exec:
          command: ["/bin/sh", "-c", "sleep 5 && kill -SIGTERM 1"]

FAQ

Ist Force Delete gefährlich?

Force Delete entfernt den Pod aus der Kubernetes-API, aber der Container kann auf dem Node noch laufen. Bei StatefulSets kann das zu doppelten Instanzen führen, die auf dasselbe Volume zugreifen. Bei stateless Pods ist es in der Regel sicher.

Was passiert mit dem PersistentVolume, wenn ich den Finalizer entferne?

Wenn Sie den kubernetes.io/pv-protection Finalizer entfernen, kann das PV gelöscht werden, obwohl noch Daten darauf liegen. Prüfen Sie vorher, ob das Volume noch benötigt wird.

Warum reicht kubectl delete pod ohne --force nicht?

Ohne --force wartet Kubernetes die terminationGracePeriodSeconds ab und schickt erst SIGTERM, dann SIGKILL. Wenn der Node nicht erreichbar ist oder ein Finalizer hängt, hilft das Warten nicht.

Kann ich Terminating-Pods per Monitoring erkennen?

Ja. Überwachen Sie die Metrik kube_pod_deletion_timestamp in Prometheus. Wenn ein Pod länger als 5 Minuten ein deletionTimestamp hat, ist er stuck.

Wenn Ihre Pods regelmäßig in Terminating hängenbleiben, liegt das Problem oft tiefer -- fehlerhafte Controller, Node-Probleme oder falsch konfigurierte Finalizer. Unser Kubernetes Troubleshooting Guide hilft Ihnen, auch andere häufige Pod-Probleme systematisch zu debuggen.