Demo Add A Finalizer To WebApp

By default the WebApp delete flow in this operator relies solely on owner references. That works for in-cluster resources like Deployments, Services, and ConfigMaps because the Kubernetes garbage collector will remove dependent objects automatically when their owner is deleted. However, some cleanup tasks cannot be inferred by Kubernetes — for example, cleaning up external cloud resources, revoking credentials, or performing any operator-specific final work. For those cases you need a finalizer on the custom resource so the controller can run cleanup before the API server actually deletes the object. The problem with the current behavior (before adding a finalizer) is demonstrated here: creating the WebApp and immediately deleting it completes quickly because nothing blocks the deletion.

$ kubectl apply -f ../webapp-site.yaml
namespace/webapp-demo created
webapp.webapp.kodekloud.com/site created

$ kubectl -n webapp-demo delete webapp site
webapp.webapp.kodekloud.com "site" deleted from webapp-demo namespace

That fast disappearance prevents the controller from performing any needed cleanup. The solution is to add a finalizer string owned by the operator and implement the standard finalizer pattern in the controller’s Reconcile logic.

controller-runtime helpers simplify adding, checking, and removing finalizers: each controller should only add and remove its own finalizer string. Using these helpers avoids manual metadata slice manipulation.

Finalizer name and placement

Use a unique, domain-style finalizer string and declare it as a package-level constant so the controller uses a single canonical value everywhere.

import (
	"sigs.k8s.io/controller-runtime/pkg/controller/controllerutil"

	webappv1 "github.com/kodekloud/webapp-operator/api/v1"
)

const webAppFinalizer = "webapp.kodekloud.com/finalizer"

For reference, the controller struct looks like:

type WebAppReconciler struct {
	client.Client
	Scheme   *runtime.Scheme
	Recorder record.EventRecorder
}

The finalizer pattern in Reconcile

A well-structured Reconcile should clearly separate two paths:

Normal (non-deleting) path — ensure the finalizer is present.
Deletion path — perform cleanup and remove the finalizer so Kubernetes can finish deletion.

Key points:

Only add the finalizer when the object is not being deleted (DeletionTimestamp == zero).
When adding the finalizer, persist the object with r.Update and then requeue so the next reconcile will operate on the object with the updated resourceVersion.
When deletion is in progress (DeletionTimestamp non-nil), only perform cleanup if your finalizer is present; then remove it and Update so the API server can complete deletion.

Add finalizer during normal reconciliation

Check the DeletionTimestamp and add the finalizer if missing. Use controllerutil.ContainsFinalizer and controllerutil.AddFinalizer to avoid unnecessary updates.

if webapp.DeletionTimestamp.IsZero() {
    if !controllerutil.ContainsFinalizer(&webapp, webAppFinalizer) {
        controllerutil.AddFinalizer(&webapp, webAppFinalizer)
        if err := r.Update(ctx, &webapp); err != nil {
            return ctrl.Result{}, err
        }
        // Requeue to fetch the object with the updated finalizer/resourceVersion
        return ctrl.Result{Requeue: true}, nil
    }
    // Continue normal reconciliation when finalizer already present
}

Deletion branch — perform cleanup, then remove finalizer

When the Resource’s DeletionTimestamp is set the API server has accepted a delete request but is holding the object until all finalizers are removed. Act only if your finalizer is present; perform any required controller-specific cleanup, then remove your finalizer and Update the object so Kubernetes can finish deletion. A full Reconcile example that demonstrates both branches:

package controllers

import (
    "context"

    appsv1 "k8s.io/api/apps/v1"
    metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
    ctrl "sigs.k8s.io/controller-runtime"
    "sigs.k8s.io/controller-runtime/pkg/client"
    "sigs.k8s.io/controller-runtime/pkg/controller/controllerutil"

    webappv1 "github.com/kodekloud/webapp-operator/api/v1"
)

const webAppFinalizer = "webapp.kodekloud.com/finalizer"

func (r *WebAppReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
    var webapp webappv1.WebApp
    if err := r.Get(ctx, req.NamespacedName, &webapp); err != nil {
        return ctrl.Result{}, client.IgnoreNotFound(err)
    }

    // 1) Normal path: object not being deleted -> ensure finalizer exists
    if webapp.DeletionTimestamp.IsZero() {
        if !controllerutil.ContainsFinalizer(&webapp, webAppFinalizer) {
            controllerutil.AddFinalizer(&webapp, webAppFinalizer)
            if err := r.Update(ctx, &webapp); err != nil {
                return ctrl.Result{}, err
            }
            // Requeue so we operate on the updated object next pass
            return ctrl.Result{Requeue: true}, nil
        }
        // Continue with normal reconciliation (omitted here)
    }

    // 2) Deletion path: object is being deleted
    if !webapp.DeletionTimestamp.IsZero() {
        // Only act if our finalizer is present
        if controllerutil.ContainsFinalizer(&webapp, webAppFinalizer) {
            // Example placeholder: build a Deployment object reference or perform other cleanup
            dep := &appsv1.Deployment{
                ObjectMeta: metav1.ObjectMeta{
                    Name:      webapp.Name,
                    Namespace: webapp.Namespace,
                },
            }

            // Perform cleanup here (e.g., delete external resources, revoke cloud resources)
            // In this demo, we'll log and consider cleanup done.
            ctrl.LoggerFrom(ctx).Info("running cleanup for WebApp", "name", webapp.Name)

            // Remove our finalizer and persist the object so Kubernetes can complete deletion
            controllerutil.RemoveFinalizer(&webapp, webAppFinalizer)
            if err := r.Update(ctx, &webapp); err != nil {
                return ctrl.Result{}, err
            }
            // After removing finalizer and successful update, the object will be deleted by the API server.
            return ctrl.Result{}, nil
        }
        // If our finalizer is not present, nothing for us to do; let deletion proceed.
    }

    return ctrl.Result{}, nil
}

Do not remove finalizers that you do not own. Always check ContainsFinalizer before calling RemoveFinalizer to avoid interfering with other controllers’ cleanup. Also return errors from Update so controller-runtime will retry on transient failures.

Verify deletion completed

Once the controller has removed its finalizer and the API server finishes deletion, a subsequent get should return NotFound:

$ kubectl -n webapp-demo get webapp site
Error from server (NotFound): webapps.webapp.kodekloud.com "site" not found

A NotFound response indicates the delete request completed successfully and the finalizer flow worked: your controller performed cleanup and released its finalizer so Kubernetes could complete deletion.

Quick summary and checklist

Step	Purpose	Example / Note
Add finalizer	Ensure controller can run cleanup before deletion	Use `controllerutil.AddFinalizer` when `DeletionTimestamp.IsZero()`
Persist change & requeue	Let next reconcile operate on updated resource	Call `r.Update(ctx, &webapp)` then `return ctrl.Result{Requeue: true}, nil`
On delete, check ownership	Only perform cleanup if your finalizer is present	`controllerutil.ContainsFinalizer(&webapp, webAppFinalizer)`
Perform cleanup	Delete external resources or perform operator-specific work	Idempotent cleanup is recommended
Remove finalizer & update	Allow API server to finish deletion	`controllerutil.RemoveFinalizer` + `r.Update`

Introduction to Operator Fundamentals

Custom Resource Definitions Deep Dive

Kubebuilder Scaffolding

Building The WebApp Operator Core Reconcile

Running Testing Debugging Locally

Status Conditions Events

Finalizers And Cleanup

Validation Webhooks And CEL Policies

Packaging And Distribution

Alternative Approaches Operator SDK Helm Operator

Consuming Popular Operators

Production Readiness Testing Wrap Up

Demo Add A Finalizer To WebApp

Finalizer name and placement

The finalizer pattern in Reconcile

Add finalizer during normal reconciliation

Deletion branch — perform cleanup, then remove finalizer

Verify deletion completed

Quick summary and checklist

References

Watch Video

Practice Lab

​Finalizer name and placement

​The finalizer pattern in Reconcile

​Add finalizer during normal reconciliation

​Deletion branch — perform cleanup, then remove finalizer

​Verify deletion completed

​Quick summary and checklist

​References

Watch Video

Practice Lab

Finalizer name and placement

The finalizer pattern in Reconcile

Add finalizer during normal reconciliation

Deletion branch — perform cleanup, then remove finalizer

Verify deletion completed

Quick summary and checklist

References