> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Finalizers And The Cleanup Flow
> Explains Kubernetes finalizers and cleanup flow so controllers reliably perform idempotent external resource cleanup before allowing object deletion, including patterns, pseudocode, and best practices.
Deleting a custom resource should not feel like pulling the power cord — it should feel like closing a ticket. Finalizers give controllers a reliable, visible opportunity to perform cleanup before Kubernetes removes the object from etcd.
Controllers get one last chance to finish the cleanup they own. If a controller only manages in-cluster children with proper ownerReferences, Kubernetes will garbage-collect those children automatically. But when the controller touches resources outside the cluster — external DNS records, cloud resources, or entries in third-party systems — the API server cannot infer how to undo that work. Finalizers solve this gap.
Creating a web app typically tells the controller to create or maintain certain resources. To delete that web app, a user runs:
```bash theme={null}
kubectl delete webapp site
```
The delete request changes the resource lifecycle: the API server sets a `deletionTimestamp` and puts the object into a Terminating state while finalizers remain. Controllers reconcile against that visible terminating object and perform any necessary cleanup before the API server finally removes the object.
If the controller must manage external resources, add a finalizer so the API server waits while the controller cleans up those outside resources.
A finalizer is just a string in `metadata.finalizers`. For example:
```yaml theme={null}
apiVersion: webapp.kodekloud.com/v1
kind: WebApp
metadata:
name: site
finalizers:
- webapp.kodekloud.com/finalizer
```
While at least one finalizer remains, the API server keeps the resource visible (Terminating) and sets `deletionTimestamp`. Controllers must reconcile that object and perform cleanup before removing their finalizer.
When finalizers are present, reconcile follows two clear paths:
* Normal path (no `deletionTimestamp`): ensure resources (in-cluster and external) exist and that your controller's finalizer is attached before creating anything that requires cleanup later.
* Cleanup path (`deletionTimestamp` set): stop creating/updating normal children, perform cleanup of owned external resources, and remove only your controller's finalizer when cleanup succeeds.
Example reconcile pseudocode showing the two paths and where to add/remove the finalizer:
```go theme={null}
func Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
var app webappv1.WebApp
if err := r.Get(ctx, req.NamespacedName, &app); err != nil {
return ctrl.Result{}, client.IgnoreNotFound(err)
}
// If not terminating: ensure finalizer and normal reconcile
if app.ObjectMeta.DeletionTimestamp.IsZero() {
if !hasFinalizer(&app) {
addFinalizer(&app)
r.Update(ctx, &app)
}
return r.normalReconcile(&app)
}
// Terminating: run cleanup, then remove finalizer
if err := r.cleanupExternalResources(&app); err != nil {
// Record error and requeue; leave finalizer so deletion is blocked
return ctrl.Result{RequeueAfter: time.Minute}, err
}
removeFinalizer(&app)
r.Update(ctx, &app)
return ctrl.Result{}, nil
}
```
When implementing this pattern, follow these guidelines:
* Add your finalizer before creating external resources — don’t create external state without protecting deletion.
* Only remove your controller's finalizer once your cleanup has completed successfully.
* Make cleanup idempotent: if it runs multiple times (controller retries/crashes), it should safely treat already-deleted resources as success.
* Record failures in Status, Events, or Logs so operators can diagnose why an object remains Terminating.
If cleanup keeps failing, the resource will remain in Terminating. That is safer than silently leaking external resources, but it requires good observability so humans can take corrective action.
```bash theme={null}
kubectl get webapp site
# NAME STATUS AGE
kubectl describe webapp site
# Events:
# Warning CleanupFailed external DNS delete timed out
```
Owner references and finalizers are complementary:
| Mechanism | Best for | Behavior |
| ----------------: | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `ownerReferences` | In-cluster children (Pods, Deployments, Services, ConfigMaps) | Kubernetes garbage-collects children automatically when the owner is deleted. |
| `finalizers` | External resources or any cleanup Kubernetes cannot perform | The API server delays object removal until all finalizers are removed; controllers must remove their finalizer after cleanup succeeds. |
Best practices for finalizers and cleanup
* Use stable, namespaced finalizer names like `webapp.kodekloud.com/finalizer` to show ownership and avoid collisions.
* Each controller should only remove the finalizers it added.
* Ensure cleanup is idempotent and resilient to transient errors.
* Surface blocking errors via Status, Events, and Logs.
There is an administrative escape hatch when cleanup is irrecoverably stuck: manually remove the finalizer. This forces Kubernetes to forget the object even if external cleanup did not complete.
```bash theme={null}
kubectl patch webapp site --type=merge \
-p '{"metadata":{"finalizers":[]}}'
```
Force-removing finalizers bypasses cleanup. Use it only as a recovery or emergency action, and after documenting the consequences.
Always add your controller's finalizer before creating external resources, and make cleanup idempotent so retries and crashes are safe.
Demo overview
The accompanying demo implements this pattern in a webapp reconciler: the controller adds a finalizer during normal reconcile, detects deletion via `deletionTimestamp`, performs a simulated external cleanup, removes its finalizer upon success, and then allows Kubernetes to complete the deletion.
Links and references
* [Kubernetes API Conventions: Finalizers](https://kubernetes.io/docs/reference/using-api/api-concepts/#finalizers)
* [Owner References and Garbage Collection](https://kubernetes.io/docs/concepts/workloads/controllers/garbage-collection/)
* [Controller pattern: Finalizers and Cleanup](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#finalizers)