Kubernetes Namespace löschen hängt: Finalizer finden und entfernen

TL;DR

kubectl delete namespace hängt in Terminating, weil Finalizer auf Ressourcen innerhalb des Namespace warten. Finden Sie die blockierenden Ressourcen mit kubectl api-resources --verbs=list -o name | xargs -n1 kubectl get -n <ns>. Dann entweder die Ressourcen sauber löschen oder den Namespace-Finalizer per Kubernetes-API entfernen.

Freitag, 22 Uhr. Sie wollen einen Test-Namespace aufräumen. kubectl delete namespace staging -- und nichts passiert. Der Namespace hängt in Terminating. Seit 20 Minuten. kubectl delete nochmal? Bringt nichts. --force? Gibt es für Namespaces nicht.

Das Problem kennt jeder Kubernetes-Admin. Die Lösung ist immer dieselbe: den blockierenden Finalizer finden und entfernen.

Was passiert beim Namespace-Löschen?

Wenn Sie einen Namespace löschen, passiert folgendes:

1. Kubernetes setzt deletionTimestamp auf den Namespace
2. Alle Ressourcen im Namespace werden gelöscht (Pods, Services, Deployments...)
3. Controller mit Finalizern räumen externe Abhängigkeiten auf
4. Erst wenn alle Finalizer entfernt sind, verschwindet der Namespace

Wenn Schritt 3 hängt -- weil ein Controller nicht läuft oder eine API nicht erreichbar ist -- bleibt der Namespace ewig in Terminating.

Schritt 1: Blockierende Ressourcen finden

# Alle Ressourcen im Namespace auflisten -- auch die, die man leicht übersieht
kubectl api-resources --verbs=list --namespaced -o name | \
  xargs -n1 -I{} kubectl get {} -n staging --no-headers 2>/dev/null | grep -v "^$"

Dieser Befehl durchsucht alle API-Ressourcentypen im Namespace. Oft finden sich hier vergessene CRDs (Custom Resource Definitions), die noch Finalizer haben.

Typische Blocker:

Schritt 2: Finalizer der blockierenden Ressourcen entfernen

Wenn Sie die blockierende Ressource gefunden haben, entfernen Sie deren Finalizer:

# Finalizer einer Custom Resource entfernen
kubectl patch certificate my-cert -n staging \
  -p '{"metadata":{"finalizers":null}}' --type=merge

# Oder bei einer unbekannten CRD
kubectl get <resource-type> -n staging -o name | \
  xargs -n1 kubectl patch -n staging -p '{"metadata":{"finalizers":null}}' --type=merge

Nach dem Entfernen des Finalizers wird die Ressource gelöscht, und der Namespace sollte folgen.

Schritt 3: Namespace-Finalizer direkt entfernen (Notlösung)

Wenn Schritt 2 nicht reicht oder Sie die blockierende Ressource nicht finden, können Sie den Finalizer direkt am Namespace entfernen. Das geht nicht mit kubectl patch, sondern nur über die Kubernetes-API:

# Namespace-JSON exportieren
kubectl get namespace staging -o json > /tmp/ns-staging.json

Editieren Sie die Datei und entfernen Sie den kubernetes Finalizer aus spec.finalizers:

{
  "apiVersion": "v1",
  "kind": "Namespace",
  "metadata": {
    "name": "staging",
    "deletionTimestamp": "2026-03-08T22:15:00Z"
  },
  "spec": {
    "finalizers": []
  }
}

Dann per API-Call aktualisieren:

# Namespace-Finalizer per API entfernen
kubectl replace --raw "/api/v1/namespaces/staging/finalize" -f /tmp/ns-staging.json

Der Namespace verschwindet sofort.

Einzeiler-Variante

Wer es schneller mag:

kubectl get namespace staging -o json | \
  jq '.spec.finalizers = []' | \
  kubectl replace --raw "/api/v1/namespaces/staging/finalize" -f -

Warum nicht einfach immer den Finalizer entfernen?

Finalizer schützen vor verwaisten Ressourcen. Wenn Sie den Namespace-Finalizer entfernen, ohne die enthaltenen Ressourcen sauber aufzuräumen, bleiben möglicherweise Cloud-Ressourcen zurück:

• Load Balancer, die weiter Kosten verursachen
• Persistent Volumes mit Daten
• DNS-Einträge, die auf nichts mehr zeigen
• IAM-Rollen oder Service Accounts beim Cloud-Provider

Versuchen Sie immer zuerst, die blockierende Ressource selbst zu bereinigen (Schritt 2), bevor Sie den Namespace-Finalizer direkt entfernen.

Häufige Szenarien und Schnellfixes

CRD wurde gelöscht, bevor der Namespace gelöscht wurde:

Das ist der häufigste Fall. Jemand deinstalliert z.B. cert-manager mit helm uninstall, was die CRDs entfernt. Die Custom Resources im Namespace haben aber noch Finalizer, und der Controller, der sie entfernen soll, existiert nicht mehr.

# CRD nochmal installieren, damit der Controller aufräumen kann
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.17.0/cert-manager.crds.yaml

# Warten bis der Namespace sich auflöst
# Dann CRDs wieder entfernen

Aggregated API Server nicht erreichbar:

# API Services prüfen -- suchen Sie nach "False" in der AVAILABLE-Spalte
kubectl get apiservices | grep False

Ein nicht erreichbarer API-Service blockiert das Namespace-Cleanup. Löschen oder reparieren Sie den API-Service.

FAQ

Kann ich kubectl delete namespace --force verwenden?

Das Flag --force existiert für Namespaces, hat aber keine Wirkung auf Finalizer. Es überspringt nur die Grace Period, die bei Namespaces ohnehin keine Rolle spielt. Der Namespace bleibt in Terminating.

Verliere ich Daten, wenn ich den Namespace-Finalizer entferne?

PersistentVolumes mit reclaimPolicy: Retain bleiben erhalten, auch wenn der Namespace gelöscht wird. Volumes mit reclaimPolicy: Delete werden gelöscht. Prüfen Sie Ihre PVs vor dem Force-Delete.

Wie verhindere ich das Problem in Zukunft?

Deinstallieren Sie Operatoren und CRD-basierte Tools immer in der richtigen Reihenfolge: Erst die Custom Resources löschen, dann den Controller, zuletzt die CRDs. Nie umgekehrt.

Wenn Pods innerhalb des Namespace ebenfalls in Terminating hängen, lesen Sie unseren Artikel Kubernetes Pod Terminating hängt für die Pod-spezifischen Lösungen.