Kubernetes Finalizers: The 'Do Not Delete Yet' Lock

WHY IT EXISTS Kubernetes garbage collection automatically cleans up dependent objects within the cluster. But when a Kubernetes object represents a resource outside the cluster, like a cloud database, deleting the object would orphan that external resource. Finalizers were created to solve this out-of-cluster cleanup problem.

THE MENTAL MODEL Think of a finalizer as a lock on a file you want to delete. The operating system won't actually erase the file until every process holding a lock on it has released it. Similarly, a finalizer is a key in an object's metadata. When you request deletion, the API server sees the key, marks the object for deletion, and waits for a controller to perform cleanup and remove the key before the object is truly gone.

HOW IT WORKS A controller adds a finalizer key to an object's metadata.finalizers list upon creation. When a user tries to delete that object, the API server sees the finalizer and, instead of deleting, adds a deletionTimestamp. The object enters a 'Terminating' state. The controller, watching for this timestamp, then runs its cleanup logic. Once the external resource is de-provisioned, the controller removes its key from the finalizers list. With the list empty, the API server completes the deletion.

WHEN TO USE IT Use finalizers when a Custom Resource's lifecycle is tied to an external resource that requires explicit, ordered cleanup. This is the core mechanism for operators that manage cloud services like databases, storage buckets, or DNS entries, ensuring no resources are orphaned.

WHEN NOT TO USE IT Avoid finalizers for simple, self-contained Kubernetes objects that don't manage anything outside the cluster. Standard owner-dependent garbage collection is sufficient and less complex. Overusing finalizers can make your cluster's deletion processes fragile and difficult to debug.

ONE CANONICAL EXAMPLE The AWS Load Balancer Controller uses finalizers. When you create an Ingress object, the controller adds a finalizer and provisions an ALB in your AWS account. When you delete the Ingress, the controller sees the deletion timestamp, de-provisions the ALB, and only then removes its finalizer, allowing Kubernetes to finally delete the Ingress object. If you just manually remove the finalizer, the Ingress object disappears but the expensive load balancer is left running in your cloud account.