🔒 Finalizer Patterns

Finalizers are strings in metadata.finalizers that act as deletion gates. An object with finalizers cannot be deleted from etcd until all finalizers are removed. Controllers are responsible for doing the cleanup work and then removing their finalizer.

Common finalizer use cases

Well-known built-in finalizers

Complete finalizer lifecycle in a controller

const myFinalizer = "cleanup.myorg.example.com"

func (r *DatabaseReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
    db := &myorgv1.Database{}
    if err := r.Get(ctx, req.NamespacedName, db); err != nil {
        return ctrl.Result{}, client.IgnoreNotFound(err)
    }

    // --- DELETION PATH ---
    if !db.DeletionTimestamp.IsZero() {
        if controllerutil.ContainsFinalizer(db, myFinalizer) {
            // Perform cleanup with a timeout
            cleanupCtx, cancel := context.WithTimeout(ctx, 60*time.Second)
            defer cancel()

            if err := r.deleteExternalResources(cleanupCtx, db); err != nil {
                // Update status to reflect cleanup failure
                db.Status.Phase = "TerminationFailed"
                r.Status().Update(ctx, db)
                return ctrl.Result{}, err
            }

            // Cleanup done — remove finalizer to allow deletion
            controllerutil.RemoveFinalizer(db, myFinalizer)
            if err := r.Update(ctx, db); err != nil {
                return ctrl.Result{}, err
            }
        }
        return ctrl.Result{}, nil  // object will be deleted
    }

    // --- CREATION PATH: add finalizer if missing ---
    if !controllerutil.ContainsFinalizer(db, myFinalizer) {
        controllerutil.AddFinalizer(db, myFinalizer)
        if err := r.Update(ctx, db); err != nil {
            return ctrl.Result{}, err
        }
        return ctrl.Result{Requeue: true}, nil  // requeue to continue reconcile
    }

    // --- NORMAL RECONCILE PATH ---
    return r.reconcileDatabase(ctx, db)
}

kubectl patch database prod-postgres \
  --type=merge \
  -p '{"metadata":{"finalizers":[]}}'

Checking for stuck resources

# Find all Terminating resources cluster-wide
kubectl get all -A | grep Terminating

# See which finalizers are blocking deletion
kubectl get database prod-postgres -o jsonpath='{.metadata.finalizers}'
# ["cleanup.myorg.example.com"]

# Check deletionTimestamp — if set, deletion is pending
kubectl get database prod-postgres -o jsonpath='{.metadata.deletionTimestamp}'
# 2024-01-15T10:30:00Z  ← deletion was requested at this time

# Check how long it's been stuck
kubectl get database prod-postgres
# NAME           PHASE               AGE
# prod-postgres  TerminationFailed   45m   ← stuck for 45 minutes

🗑️ Deletion Policies — Three Modes

When you delete a resource with dependents, Kubernetes supports three propagation policies. You control this via the --cascade flag or the propagationPolicy field in the delete options.

Controlling deletion policy with kubectl

# Background (default) — owner gone immediately, GC cleans up children async
kubectl delete deployment my-app
kubectl delete deployment my-app --cascade=background   # explicit

# Foreground — wait for all dependents to be deleted first
kubectl delete deployment my-app --cascade=foreground

# Orphan — delete the Deployment but keep the ReplicaSets and Pods
kubectl delete deployment my-app --cascade=orphan

# Via API with propagationPolicy in delete options
kubectl proxy &
curl -X DELETE localhost:8001/apis/apps/v1/namespaces/default/deployments/my-app \
  -H "Content-Type: application/json" \
  -d '{"kind":"DeleteOptions","apiVersion":"v1","propagationPolicy":"Foreground"}'

Foreground deletion — the lifecycle

Orphan policy — adopting orphaned resources

# Delete a ReplicaSet without deleting its Pods (orphan them)
kubectl delete rs my-app-7d9f8 --cascade=orphan

# The pods now have no controller — they won't be rescheduled if they die
# A new ReplicaSet with the same selector will "adopt" them if created

# Verify: pods still Running, no ownerReference
kubectl get pods -l app=my-app -o jsonpath='{range .items[*]}{.metadata.name}: {.metadata.ownerReferences}{"\n"}{end}'
# my-app-abc: []   ← orphaned, no owner

🧠 Knowledge Check