📖 docs for using finalizers

Author: droot

docs/book/src/SUMMARY.md

@@ -26,4 +26,10 @@
 
 ---
 
+- [Reference](./reference/reference.md)
+
+  - [Using Finalizers](./reference/using-finalizers.md)
+
+---
+
 [Appendix: The TODO Landing Page](./TODO.md)

docs/book/src/cronjob-tutorial/testdata/finalizer_example.go

@@ -0,0 +1,116 @@
+/*
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+// +kubebuilder:docs-gen:collapse=Apache License
+
+/*
+First, we start out with some standard imports.
+As before, we need the core controller-runtime library, as well as
+the client package, and the package for our API types.
+*/
+package controllers
+
+import (
+	"context"
+
+	"github.com/go-logr/logr"
+	ctrl "sigs.k8s.io/controller-runtime"
+	"sigs.k8s.io/controller-runtime/pkg/client"
+
+	batchv1 "tutorial.kubebuilder.io/project/api/v1"
+)
+
+// +kubebuilder:docs-gen:collapse=Imports
+
+/*
+The code snippet below shows skeleton code for implementing a finalizer.
+*/
+
+func (r *CronJobReconciler) Reconcile(req ctrl.Request) (ctrl.Result, error) {
+	ctx := context.Background()
+	log := r.Log.WithValues("cronjob", req.NamespacedName)
+
+	var cronJob batch.CronJob
+	if err := r.Get(ctx, req.NamespacedName, &cronJob); err != nil {
+		log.Error(err, "unable to fetch CronJob")
+		// we'll ignore not-found errors, since they can't be fixed by an immediate
+		// requeue (we'll need to wait for a new notification), and we can get them
+		// on deleted requests.
+		return ctrl.Result{}, ignoreNotFound(err)
+	}
+
+	// name of our custom finalizer
+	myFinalizerName := "storage.finalizers.tutorial.kubebuilder.io"
+
+	// examine DeletionTimestamp to determine if object is under deletion
+	if cronJob.ObjectMeta.DeletionTimestamp.IsZero() {
+		// The object is not being deleted, so if it does not have our finalizer,
+		// then lets add the finalizer and update the object. This is equivalent
+		// registering our finalizer.
+		if !containsString(cronJob.ObjectMeta.Finalizers, myFinalizerName) {
+			cronJob.ObjectMeta.Finalizers = append(cronJob.ObjectMeta.Finalizers, myFinalizerName)
+			if err := r.Update(context.Background(), cronJob); err != nil {
+				return ctrl.Result{}, err
+			}
+		}
+	} else {
+		// The object is being deleted
+		if containsString(cronJob.ObjectMeta.Finalizers, myFinalizerName) {
+			// our finalizer is present, so lets handle any external dependency
+			if err := r.deleteExternalResources(cronJob); err != nil {
+				// if fail to delete the external dependency here, return with error
+				// so that it can be retried
+				return ctrl.Result{}, err
+			}
+
+			// remove our finalizer from the list and update it.
+			cronJob.ObjectMeta.Finalizers = removeString(cronJob.ObjectMeta.Finalizers, myFinalizerName)
+			if err := r.Update(context.Background(), cronJob); err != nil {
+				return ctrl.Result{}, err
+			}
+		}
+
+		return ctrl.Result{}, err
+	}
+
+	// rest of the reconciler code
+}
+
+func (r *Reconciler) deleteExternalResources(cronJob *batch.CronJob) error {
+	//
+	// delete any external resources associated with the cronJob
+	//
+	// Ensure that delete implementation is idempotent and safe to invoke
+	// multiple types for same object.
+}
+
+// Helper functions to check and remove string from a slice of strings.
+func containsString(slice []string, s string) bool {
+	for _, item := range slice {
+		if item == s {
+			return true
+		}
+	}
+	return false
+}
+
+func removeString(slice []string, s string) (result []string) {
+	for _, item := range slice {
+		if item == s {
+			continue
+		}
+		result = append(result, item)
+	}
+	return
+}

docs/book/src/reference/reference.md

@@ -0,0 +1,5 @@
+# Reference
+  
+  - [Using Finalizers](./using-finalizers.md): Finalizers are a mechanism to
+	execute any custom logic related to a resource before it gets deleted from
+	Kubernetes cluster.

docs/book/src/reference/using-finalizers.md

@@ -0,0 +1,25 @@
+# Using Finalizers
+
+`Finalizers` allow controllers to implement asynchronous pre-delete hooks. Let's
+say you create an external resource (such as a storage bucket) for each object of
+your API type, and you want to delete the associated external resource
+on object's deletion from Kubernetes, you can use a finalizer to do that.
+
+You can read more about the finalizers in the [Kubernetes reference docs](https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/#finalizers). The section below demonstrates how to register and trigger pre-delete hooks
+in the `Reconcile` method of a controller.
+
+The key point to note is that a finalizer causes "delete" on the object to become 
+an "update" to set deletion timestamp. Presence of deletion timestamp on the object
+indicates that it is being deleted. Otherwise, without finalizers, a delete
+shows up as a reconcile where the object is missing from the cache.
+
+Highlights:
+- If the object is not being deleted and does not have the finalizer registered,
+  then add the finalizer and update the object in Kubernetes.
+- If object is being deleted and the finalizer is still present in finalizers list,
+  then execute the pre-delete logic and remove the finalizer and update the
+  object.
+- Ensure that the pre-delete logic is idempotent.
+
+{{#literatego ../cronjob-tutorial/testdata/finalizer_example.go}}
+