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

> Beim Versuch, einen Kubernetes Namespace zu löschen, bleibt dieser dauerhaft im Terminating-Status hängen? Der Übeltäter sind typischerweise Finalizers, spezielle Metadaten-Felder, die das Löschen von Ressourcen verhindern, bis Bereinigungsaufgaben abgeschlossen sind.

- URL: https://ashkmb.com/de/blog/kubernetes-finalizers-explained/
- Author: Ashkan Kamyab (https://ashkmb.com)
- Published: 2025-10-21
- Language: de

## 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

```bash
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:

```bash
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:

```yaml
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.
