Kubernetes Finalizers Explained: Why Namespaces Get Stuck in Terminating State

kubernetes devops debugging

Introduction

Attempting to delete a Kubernetes namespace and discovering it perpetually stuck in a “Terminating” state represents one of DevOps’ most frustrating recurring issues. The culprit typically involves finalizers, special metadata fields that prevent resource deletion until cleanup tasks complete.

What Are Kubernetes Finalizers?

A finalizer functions as a “to-do list” for Kubernetes controllers. Before the Kubernetes API Server actually removes an object from etcd (the cluster’s database), it checks the list of finalizers attached to that resource.

Each finalizer entry represents a controller responsible for cleanup operations before the Kubernetes API permits actual deletion.

Why Finalizers Exist

Finalizers enable safe, predictable resource cleanup by preventing orphaned resources, like persistent volumes, network interfaces, or IAM roles, from remaining after deletion.

Common use cases include:

  • PersistentVolumeClaims (PVCs) – Ensuring associated PersistentVolumes detach before removal
  • Namespaces – Guaranteeing all sub-resources delete before namespace removal
  • Custom Resource Definitions (CRDs) – Enabling operator cleanup before instance deletion
  • Service Controllers – Cloud integrations managing load balancer deletion

How Finalizers Work

The lifecycle follows these steps:

  1. kubectl delete executes on an object
  2. Kubernetes adds a deletionTimestamp to the object
  3. Controllers managing finalizers identify the timestamp and initiate cleanup
  4. After cleanup completion, the controller removes its finalizer
  5. Once the finalizer list empties, Kubernetes deletes the object

When Things Go Wrong

Controllers occasionally crash, get removed, or malfunction. When this occurs, Kubernetes waits indefinitely for cleanup that never happens, leaving resources stuck in “Terminating.”

Typical symptoms:

  • Resource stuck in “Terminating” state
  • kubectl delete never completes
  • Finalizers remain present in object YAML
  • Controller logs display errors or missing references

Debugging a Stuck Namespace or Resource

Step 1: Inspect the Resource

kubectl get ns my-namespace -o yaml

This reveals the finalizers field blocking deletion.

Step 2: Identify the Stuck Finalizer

Check relevant controller logs to understand which finalizer prevents deletion and why cleanup isn’t progressing.

Step 3: Remove the Finalizer

Once certain removal is safe, patch the resource:

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

Alternatively, edit directly via kubectl edit ns my-namespace and delete finalizer lines.

Critical caution: Only remove finalizers after confirming cleanup is unnecessary; otherwise orphaned cloud resources may persist.

Real-World Example

Consider a namespace managed by the AWS Load Balancer Controller. Deletion reveals:

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

If the controller is unavailable or lacks proper permissions, it cannot remove the finalizer, leaving the namespace perpetually terminating.

Solution: Restart the controller or repair permissions; if unsuccessful and confident no resources remain, manually remove the finalizer.

Best Practices

  1. Avoid manual finalizer removal unless necessary; address controller issues first
  2. Examine controller logs for underlying causes
  3. Recognize that some finalizers perform critical cleanup preventing resource leaks
  4. Exercise caution with automated cleanup scripts; implement safeguards
  5. For CRD developers: register finalizers responsibly, perform cleanup in Reconcile logic, and remove after success

Conclusion

Finalizers represent subtle yet powerful Kubernetes mechanisms ensuring safe resource cleanup. They establish “cleanup contracts” between controllers and the API server. When controllers malfunction, resources become stuck, but understanding finalizer mechanics enables confident troubleshooting and safe removal.

$ cat KUBERNETES .md
· 10 min read

The Upstream Is Archived. The CVE Is Not.

Two unauthenticated NGINX HTTP/2 RCEs landed overnight, and our ingress controllers were exposed. The usual fix, bumping to the latest release, closed nothing: ingress-nginx was archived in March, and its last release ships an NGINX that will never be patched. This is how I proved what was reachable, turned HTTP/2 off as a stopgap, backported the fixes into our own build, and rolled it out without an outage.

kubernetes security devops helm nginx
$ cat KUBERNETES .md
· 7 min read

The Cluster Used 160 Millicores. Its Requests Needed Six Nodes.

Before our first customer I asked whether three medium nodes could hold production. The cluster was using about 160 millicores of CPU, yet its resource requests kept six nodes busy. Here is why requests, not usage, decide node count, why the autoscalers read requests too, and why the capacity of a cluster is not the capacity of the product when the expensive work runs at a vendor.

kubernetes eks finops devops mechanism