Q: What is a finalizer and when would you use one?
A finalizer is a string in metadata.finalizers that tells Kubernetes to keep an object until a controller finishes cleanup and removes that string.
Want to master this scenario in a live sandbox? KodeKloud's CKA & CKAD Hands-On Certification Track covers this exact problem with hands-on terminal drills.
🛠️ Production Runbook & Step-by-Step Resolution
Direct Answer: <strong>A finalizer is a string in <code>metadata.finalizers</code> that tells Kubernetes to keep an object until a controller finishes cleanup and removes that string.</strong> When you delete an object that has finalizers, the API server only sets <code>deletionTimestamp</code>; the object stays in a Terminating state until the list is empty. You use one when deleting an object requires external or ordered cleanup, such as releasing a cloud load balancer or disk. Interviewers ask because stuck Terminating namespaces and PVCs are common incidents, and the wrong fix, force-removing finalizers, can leak resources.
Mental model: two-phase deletion
Finalizers turn deletion into a request that controllers get to complete, rather than an instant removal.
- Delete request: if finalizers exist, the API server sets
metadata.deletionTimestampand keeps the object. It becomes read-mostly: you can remove finalizers but cannot add new ones. - Controller work: the owning controller sees the timestamp, performs cleanup, then removes its own finalizer entry with a patch.
- Final removal: when the finalizers list is empty and a deletionTimestamp is set, the API server deletes the object for real.
- Built-in examples:
kubernetes.io/pvc-protectionkeeps a PVC while a pod uses it, andforegroundDeletionmakes owners wait for dependents to be removed. - Owner references vs finalizers: ownerReferences drive garbage collection of dependents when the owner is deleted, while finalizers let a controller block deletion of the object itself until its own cleanup finishes. They solve different problems.
Hands-on: what is a finalizer, inspect one on a live object
Look at the metadata and see which controller owns the pending cleanup.
# See finalizers and deletion state
kubectl -n prod get pvc data-0 -o jsonpath='{.metadata.finalizers}{"\n"}{.metadata.deletionTimestamp}{"\n"}'
# Everything in a namespace that is waiting to be deleted
kubectl -n prod get pods,pvc,svc -o json | \
jq -r '.items[] | select(.metadata.deletionTimestamp) | .kind+"/"+.metadata.name'
kubectl -n prod describe pvc data-0 | sed -n '/Events/,$p'
- Read:
kubectl get <kind> <name> -o jsonpathshows finalizers and deletionTimestamp. - Identify the owner: the finalizer name usually encodes the controller domain, for example a storage, ingress or operator name.
- Check the controller: events on the object and the controller's logs say why cleanup has not finished, so read them before touching the finalizer.
- List stuck objects: filter by deletionTimestamp across a namespace to find everything waiting.
- Deletion propagation:
kubectl delete --cascade=foregrounduses theforegroundDeletionfinalizer so dependents are removed first, whereas--cascade=orphanleaves dependents behind.
When you would use a finalizer
Use one when deleting the Kubernetes object must trigger cleanup that cannot be done by garbage collection alone.
# Custom resource with a finalizer (the controller sets this when it creates the cloud resource)
apiVersion: example.com/v1
kind: Database
metadata:
name: orders-db
finalizers:
- example.com/cleanup-cloud-db
# Controller logic (pseudocode)
# if obj.deletionTimestamp is set and finalizer present:
# delete cloud database (idempotent)
# remove finalizer via patch
- External resources: an operator that provisions a cloud database, DNS record or bucket adds a finalizer so the external resource is deleted before the custom resource disappears.
- Ordered teardown: remove dependents or drain data first, then release the parent.
- Protection: prevent accidental deletion of in-use objects, as PVC and PV protection do.
- Not for everything: if ownerReferences and normal garbage collection suffice, a finalizer only adds a way for objects to get stuck.
- PVC and PV protection: a PVC used by a running pod stays Terminating until the pod is gone, which is expected behaviour, not a bug, and the fix is to delete or stop the pod.
Failure modes: stuck in Terminating
The usual cause is that the controller is gone, broken or unable to finish cleanup.
# Preferred: fix the controller, or restore it, and let it finish
# Last resort: remove the finalizers (cleanup is SKIPPED)
kubectl -n prod patch pvc data-0 --type=merge -p '{"metadata":{"finalizers":null}}'
# Find what blocks a Terminating namespace
kubectl api-resources --verbs=list --namespaced -o name | \
xargs -n1 kubectl -n stuck-ns get --ignore-not-found --show-kind
- Controller uninstalled first: deleting an operator before its custom resources leaves objects with finalizers nobody removes.
- Cleanup failing: external API errors, missing credentials or a blocked network keep the controller retrying forever.
- Namespace stuck: a namespace waits for all contents to be gone. Find remaining resources, including custom resources, and fix the real blocker. Namespaces also have
spec.finalizershandled through the/finalizesubresource. - Last-resort removal: clearing finalizers deletes the Kubernetes object but skips the cleanup, so external resources may leak and must be checked manually.
- Patch carefully: removing one entry from a finalizer list by merge patch replaces the whole list, so use a JSON patch or
kubectl editwhen other finalizers must stay in place.
Production practice for finalizer-based controllers
Well-behaved finalizer code is idempotent and observable.
- Add early, remove late: add the finalizer when you create the external resource, and remove it only after confirmed deletion.
- Idempotent cleanup: cleanup may run many times, so treat a missing external resource as success.
- Alerts: alert on objects whose deletionTimestamp is older than a threshold, for example with kube-state-metrics where available.
- Runbook: document the owner and safe manual cleanup for each finalizer your platform uses, and uninstall operators only after deleting their resources.
- A finalizer is a key in metadata.finalizers that blocks final deletion until a controller finishes cleanup and removes it; delete just sets deletionTimestamp.
- I use it for external resources or ordered teardown, and I debug stuck objects by reading finalizers, events and the owning controller's logs.
- Only as a last resort do I patch finalizers to null, then I check for leaked cloud resources.
Senior hiring managers and bar raisers evaluate how you prioritize during outages. Avoid these common anti-patterns:
- Force-clearing finalizers as the first fix It skips cleanup and can leak disks, load balancers or cloud records.
- Uninstalling an operator before deleting its custom resources Their finalizers have no controller to remove them, leaving objects stuck.
- Adding a finalizer without idempotent cleanup Retries or partial failures then block deletion forever.
- Using finalizers where ownerReferences suffice It adds a failure mode with no benefit.