Kubernetes Finalizers erklärt: Warum Namespaces im Terminating-Status hängen bleiben

kubernetes devops debugging

Einführung

Der Versuch, einen Kubernetes Namespace zu löschen, nur um festzustellen, dass dieser dauerhaft im “Terminating”-Status hängen bleibt, gehört zu den frustrierendsten wiederkehrenden Problemen im DevOps-Bereich. Der Übeltäter sind typischerweise Finalizers, spezielle Metadaten-Felder, die das Löschen von Ressourcen verhindern, bis Bereinigungsaufgaben abgeschlossen sind.

Was sind Kubernetes Finalizers?

Ein Finalizer funktioniert als eine Art “Aufgabenliste” für Kubernetes Controller. Bevor der Kubernetes API Server ein Objekt tatsächlich aus etcd (der Cluster-Datenbank) entfernt, prüft er die Liste der Finalizers, die an die jeweilige Ressource angehängt sind.

Jeder Finalizer-Eintrag repräsentiert einen Controller, der für Bereinigungsoperationen verantwortlich ist, bevor die Kubernetes API die tatsächliche Löschung erlaubt.

Warum Finalizers existieren

Finalizers ermöglichen eine sichere und vorhersagbare Ressourcenbereinigung, indem sie verhindern, dass verwaiste Ressourcen, wie Persistent Volumes, Netzwerkschnittstellen oder IAM-Rollen, nach dem Löschen bestehen bleiben.

Häufige Anwendungsfälle umfassen:

  • PersistentVolumeClaims (PVCs) – Sicherstellen, dass zugehörige PersistentVolumes vor der Entfernung getrennt werden
  • Namespaces – Gewährleisten, dass alle Unterressourcen vor der Namespace-Entfernung gelöscht werden
  • Custom Resource Definitions (CRDs) – Ermöglichen der Operator-Bereinigung vor der Instanz-Löschung
  • Service Controller – Cloud-Integrationen, die das Löschen von Load Balancern verwalten

Wie Finalizers funktionieren

Der Lebenszyklus folgt diesen Schritten:

  1. kubectl delete wird auf ein Objekt ausgeführt
  2. Kubernetes fügt dem Objekt einen deletionTimestamp hinzu
  3. Controller, die Finalizers verwalten, erkennen den Zeitstempel und starten die Bereinigung
  4. Nach Abschluss der Bereinigung entfernt der Controller seinen Finalizer
  5. Sobald die Finalizer-Liste leer ist, löscht Kubernetes das Objekt

Wenn etwas schiefgeht

Controller können gelegentlich abstürzen, entfernt werden oder Fehlfunktionen aufweisen. Wenn dies geschieht, wartet Kubernetes endlos auf eine Bereinigung, die nie stattfindet, und hinterlässt Ressourcen im “Terminating”-Status.

Typische Symptome:

  • Ressource bleibt im “Terminating”-Status hängen
  • kubectl delete wird nie abgeschlossen
  • Finalizers bleiben im Objekt-YAML vorhanden
  • Controller-Logs zeigen Fehler oder fehlende Referenzen an

Debugging eines hängengebliebenen Namespace oder einer Ressource

Schritt 1: Die Ressource untersuchen

kubectl get ns my-namespace -o yaml

Dies zeigt das Finalizers-Feld an, das die Löschung blockiert.

Schritt 2: Den blockierenden Finalizer identifizieren

Prüfen Sie die relevanten Controller-Logs, um zu verstehen, welcher Finalizer die Löschung verhindert und warum die Bereinigung nicht voranschreitet.

Schritt 3: Den Finalizer entfernen

Sobald sicher ist, dass die Entfernung unbedenklich ist, patchen Sie die Ressource:

kubectl patch ns my-namespace -p '{"metadata":{"finalizers":[]}}' --type=merge

Alternativ können Sie direkt über kubectl edit ns my-namespace bearbeiten und die Finalizer-Zeilen löschen.

Wichtiger Hinweis: Entfernen Sie Finalizers nur, nachdem Sie bestätigt haben, dass keine Bereinigung erforderlich ist; andernfalls können verwaiste Cloud-Ressourcen bestehen bleiben.

Praxisbeispiel

Betrachten Sie einen Namespace, der vom AWS Load Balancer Controller verwaltet wird. Bei der Löschung zeigt sich:

metadata:
  finalizers:
  - service.kubernetes.io/load-balancer-cleanup

Wenn der Controller nicht verfügbar ist oder nicht über die richtigen Berechtigungen verfügt, kann er den Finalizer nicht entfernen, und der Namespace bleibt dauerhaft im Terminating-Status.

Lösung: Starten Sie den Controller neu oder reparieren Sie die Berechtigungen; wenn dies nicht erfolgreich ist und Sie sicher sind, dass keine Ressourcen mehr vorhanden sind, entfernen Sie den Finalizer manuell.

Best Practices

  1. Vermeiden Sie das manuelle Entfernen von Finalizers, es sei denn, es ist notwendig; beheben Sie zuerst Controller-Probleme
  2. Untersuchen Sie Controller-Logs auf zugrundeliegende Ursachen
  3. Beachten Sie, dass einige Finalizers kritische Bereinigungen durchführen, die Ressourcenlecks verhindern
  4. Seien Sie vorsichtig mit automatisierten Bereinigungsskripten; implementieren Sie Sicherheitsmechanismen
  5. Für CRD-Entwickler: Registrieren Sie Finalizers verantwortungsvoll, führen Sie die Bereinigung in der Reconcile-Logik durch und entfernen Sie sie nach Erfolg

Fazit

Finalizers sind subtile, aber leistungsstarke Kubernetes-Mechanismen, die eine sichere Ressourcenbereinigung gewährleisten. Sie etablieren “Bereinigungsverträge” zwischen Controllern und dem API Server. Wenn Controller Fehlfunktionen aufweisen, bleiben Ressourcen hängen, aber das Verständnis der Finalizer-Mechanik ermöglicht sicheres Troubleshooting und zuverlässige Entfernung.

$ cat KUBERNETES .md
· 10 Min. Lesezeit

Das Upstream-Projekt ist archiviert. Die CVE nicht.

Über Nacht kamen zwei NGINX-HTTP/2-Lücken, die Remote Code Execution ohne Authentifizierung erlauben, und unsere Ingress-Controller waren betroffen. Der übliche Fix, ein Update auf das neueste Release, schloss nichts: ingress-nginx wurde im März archiviert, und sein letztes Release enthält ein NGINX, das nie mehr gepatcht wird. So habe ich nachgewiesen, was tatsächlich erreichbar war, HTTP/2 als Notlösung abgeschaltet, die Fixes in einen eigenen Build zurückportiert und ihn ohne Ausfall ausgerollt.

kubernetes security devops helm nginx
$ cat KUBERNETES .md
· 6 Min. Lesezeit

Der Cluster nutzte 160 Millicores. Seine Requests brauchten sechs Nodes.

Vor unserem ersten Kunden fragte ich, ob drei mittelgroße Nodes die Produktion tragen können. Der Cluster nutzte etwa 160 Millicores CPU, doch seine Resource-Requests hielten sechs Nodes beschäftigt. Hier steht, warum Requests und nicht die Nutzung die Node-Anzahl bestimmen, warum auch die Autoscaler Requests lesen und warum die Kapazität eines Clusters nicht die Kapazität des Produkts ist, wenn die teure Arbeit bei einem Anbieter läuft.

kubernetes eks finops devops mechanism