Merge pull request kubernetes-sigs#1481 from rashmigottipati/finalizer-library

✨Finalizer helper library

Author: k8s-ci-robot

pkg/finalizer/finalizer.go

@@ -0,0 +1,79 @@
+/*
+Copyright 2021 The Kubernetes Authors.
+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.
+*/
+
+package finalizer
+
+import (
+	"context"
+	"fmt"
+
+	utilerrors "k8s.io/apimachinery/pkg/util/errors"
+	"sigs.k8s.io/controller-runtime/pkg/client"
+	"sigs.k8s.io/controller-runtime/pkg/controller/controllerutil"
+)
+
+type finalizers map[string]Finalizer
+
+// Result struct holds information about what parts of an object were updated by finalizer(s).
+type Result struct {
+	// Updated will be true if at least one of the object's non-status field
+	// was updated by some registered finalizer.
+	Updated bool
+	// StatusUpdated will be true if at least one of the object's status' fields
+	// was updated by some registered finalizer.
+	StatusUpdated bool
+}
+
+// NewFinalizers returns the Finalizers interface
+func NewFinalizers() Finalizers {
+	return finalizers{}
+}
+
+func (f finalizers) Register(key string, finalizer Finalizer) error {
+	if _, ok := f[key]; ok {
+		return fmt.Errorf("finalizer for key %q already registered", key)
+	}
+	f[key] = finalizer
+	return nil
+}
+
+func (f finalizers) Finalize(ctx context.Context, obj client.Object) (Result, error) {
+	var (
+		res     Result
+		errList []error
+	)
+	res.Updated = false
+	for key, finalizer := range f {
+		if dt := obj.GetDeletionTimestamp(); dt.IsZero() && !controllerutil.ContainsFinalizer(obj, key) {
+			controllerutil.AddFinalizer(obj, key)
+			res.Updated = true
+		} else if !dt.IsZero() && controllerutil.ContainsFinalizer(obj, key) {
+			finalizerRes, err := finalizer.Finalize(ctx, obj)
+			if err != nil {
+				// Even when the finalizer fails, it may need to signal to update the primary
+				// object (e.g. it may set a condition and need a status update).
+				res.Updated = res.Updated || finalizerRes.Updated
+				res.StatusUpdated = res.StatusUpdated || finalizerRes.StatusUpdated
+				errList = append(errList, fmt.Errorf("finalizer %q failed: %v", key, err))
+			} else {
+				// If the finalizer succeeds, we remove the finalizer from the primary
+				// object's metadata, so we know it will need an update.
+				res.Updated = true
+				controllerutil.RemoveFinalizer(obj, key)
+				// The finalizer may have updated the status too.
+				res.StatusUpdated = res.StatusUpdated || finalizerRes.StatusUpdated
+			}
+		}
+	}
+	return res, utilerrors.NewAggregate(errList)
+}

pkg/finalizer/finalizer_test.go

@@ -0,0 +1,216 @@
+package finalizer
+
+import (
+	"context"
+	"fmt"
+	"testing"
+
+	. "github.com/onsi/ginkgo"
+	. "github.com/onsi/gomega"
+	corev1 "k8s.io/api/core/v1"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"sigs.k8s.io/controller-runtime/pkg/client"
+	"sigs.k8s.io/controller-runtime/pkg/envtest/printer"
+)
+
+type mockFinalizer struct {
+	result Result
+	err    error
+}
+
+func (f mockFinalizer) Finalize(context.Context, client.Object) (Result, error) {
+	return f.result, f.err
+}
+func TestFinalizer(t *testing.T) {
+	RegisterFailHandler(Fail)
+	suiteName := "Finalizer Suite"
+	RunSpecsWithDefaultAndCustomReporters(t, suiteName, []Reporter{printer.NewlineReporter{}, printer.NewProwReporter(suiteName)})
+}
+
+var _ = Describe("TestFinalizer", func() {
+	var err error
+	var pod *corev1.Pod
+	var finalizers Finalizers
+	var f mockFinalizer
+	BeforeEach(func() {
+		pod = &corev1.Pod{
+			ObjectMeta: metav1.ObjectMeta{},
+		}
+		finalizers = NewFinalizers()
+		f = mockFinalizer{}
+	})
+	Describe("Register", func() {
+		It("successfully registers a finalizer", func() {
+			err = finalizers.Register("finalizers.sigs.k8s.io/testfinalizer", f)
+			Expect(err).To(BeNil())
+		})
+
+		It("should fail when trying to register a finalizer that was already registered", func() {
+			err = finalizers.Register("finalizers.sigs.k8s.io/testfinalizer", f)
+			Expect(err).To(BeNil())
+
+			// calling Register again with the same key should return an error
+			err = finalizers.Register("finalizers.sigs.k8s.io/testfinalizer", f)
+			Expect(err).NotTo(BeNil())
+			Expect(err.Error()).To(ContainSubstring("already registered"))
+
+		})
+	})
+
+	Describe("Finalize", func() {
+		It("successfully finalizes and returns true for Updated when deletion timestamp is nil and finalizer does not exist", func() {
+			err = finalizers.Register("finalizers.sigs.k8s.io/testfinalizer", f)
+			Expect(err).To(BeNil())
+
+			pod.DeletionTimestamp = nil
+			pod.Finalizers = []string{}
+
+			result, err := finalizers.Finalize(context.TODO(), pod)
+			Expect(err).To(BeNil())
+			Expect(result.Updated).To(BeTrue())
+			// when deletion timestamp is nil and finalizer is not present, the registered finalizer would be added to the obj
+			Expect(len(pod.Finalizers)).To(Equal(1))
+			Expect(pod.Finalizers[0]).To(Equal("finalizers.sigs.k8s.io/testfinalizer"))
+
+		})
+
+		It("successfully finalizes and returns true for Updated when deletion timestamp is not nil and the finalizer exists", func() {
+			now := metav1.Now()
+			pod.DeletionTimestamp = &now
+
+			err = finalizers.Register("finalizers.sigs.k8s.io/testfinalizer", f)
+			Expect(err).To(BeNil())
+
+			pod.Finalizers = []string{"finalizers.sigs.k8s.io/testfinalizer"}
+
+			result, err := finalizers.Finalize(context.TODO(), pod)
+			Expect(err).To(BeNil())
+			Expect(result.Updated).To(BeTrue())
+			// finalizer will be removed from the obj upon successful finalization
+			Expect(len(pod.Finalizers)).To(Equal(0))
+		})
+
+		It("should return no error and return false for Updated when deletion timestamp is nil and finalizer doesn't exist", func() {
+			pod.DeletionTimestamp = nil
+			pod.Finalizers = []string{}
+
+			result, err := finalizers.Finalize(context.TODO(), pod)
+			Expect(err).To(BeNil())
+			Expect(result.Updated).To(BeFalse())
+			Expect(len(pod.Finalizers)).To(Equal(0))
+
+		})
+
+		It("should return no error and return false for Updated when deletion timestamp is not nil and the finalizer doesn't exist", func() {
+			now := metav1.Now()
+			pod.DeletionTimestamp = &now
+			pod.Finalizers = []string{}
+
+			result, err := finalizers.Finalize(context.TODO(), pod)
+			Expect(err).To(BeNil())
+			Expect(result.Updated).To(BeFalse())
+			Expect(len(pod.Finalizers)).To(Equal(0))
+
+		})
+
+		It("successfully finalizes multiple finalizers and returns true for Updated when deletion timestamp is not nil and the finalizer exists", func() {
+			now := metav1.Now()
+			pod.DeletionTimestamp = &now
+
+			err = finalizers.Register("finalizers.sigs.k8s.io/testfinalizer", f)
+			Expect(err).To(BeNil())
+
+			err = finalizers.Register("finalizers.sigs.k8s.io/newtestfinalizer", f)
+			Expect(err).To(BeNil())
+
+			pod.Finalizers = []string{"finalizers.sigs.k8s.io/testfinalizer", "finalizers.sigs.k8s.io/newtestfinalizer"}
+
+			result, err := finalizers.Finalize(context.TODO(), pod)
+			Expect(err).To(BeNil())
+			Expect(result.Updated).To(BeTrue())
+			Expect(result.StatusUpdated).To(BeFalse())
+			Expect(len(pod.Finalizers)).To(Equal(0))
+		})
+
+		It("should return result as false and a non-nil error", func() {
+			now := metav1.Now()
+			pod.DeletionTimestamp = &now
+			pod.Finalizers = []string{"finalizers.sigs.k8s.io/testfinalizer"}
+
+			f.result.Updated = false
+			f.result.StatusUpdated = false
+			f.err = fmt.Errorf("finalizer failed for %q", pod.Finalizers[0])
+
+			err = finalizers.Register("finalizers.sigs.k8s.io/testfinalizer", f)
+			Expect(err).To(BeNil())
+
+			result, err := finalizers.Finalize(context.TODO(), pod)
+			Expect(err).ToNot(BeNil())
+			Expect(err.Error()).To(ContainSubstring("finalizer failed"))
+			Expect(result.Updated).To(BeFalse())
+			Expect(result.StatusUpdated).To(BeFalse())
+			Expect(len(pod.Finalizers)).To(Equal(1))
+			Expect(pod.Finalizers[0]).To(Equal("finalizers.sigs.k8s.io/testfinalizer"))
+		})
+
+		It("should return expected result values and error values when registering multiple finalizers", func() {
+			now := metav1.Now()
+			pod.DeletionTimestamp = &now
+			pod.Finalizers = []string{
+				"finalizers.sigs.k8s.io/testfinalizer1",
+				"finalizers.sigs.k8s.io/testfinalizer2",
+				"finalizers.sigs.k8s.io/testfinalizer3",
+			}
+
+			// registering multiple finalizers with different return values
+			// test for Updated as true, and nil error
+			f.result.Updated = true
+			f.result.StatusUpdated = false
+			f.err = nil
+			err = finalizers.Register("finalizers.sigs.k8s.io/testfinalizer1", f)
+			Expect(err).To(BeNil())
+
+			result, err := finalizers.Finalize(context.TODO(), pod)
+			Expect(err).To(BeNil())
+			Expect(result.Updated).To(BeTrue())
+			Expect(result.StatusUpdated).To(BeFalse())
+			// `finalizers.sigs.k8s.io/testfinalizer1` will be removed from the list
+			// of finalizers, so length will be 2.
+			Expect(len(pod.Finalizers)).To(Equal(2))
+			Expect(pod.Finalizers[0]).To(Equal("finalizers.sigs.k8s.io/testfinalizer2"))
+			Expect(pod.Finalizers[1]).To(Equal("finalizers.sigs.k8s.io/testfinalizer3"))
+
+			// test for Updated and StatusUpdated as false, and non-nil error
+			f.result.Updated = false
+			f.result.StatusUpdated = false
+			f.err = fmt.Errorf("finalizer failed")
+			err = finalizers.Register("finalizers.sigs.k8s.io/testfinalizer2", f)
+			Expect(err).To(BeNil())
+
+			result, err = finalizers.Finalize(context.TODO(), pod)
+			Expect(err).ToNot(BeNil())
+			Expect(err.Error()).To(ContainSubstring("finalizer failed"))
+			Expect(result.Updated).To(BeFalse())
+			Expect(result.StatusUpdated).To(BeFalse())
+			Expect(len(pod.Finalizers)).To(Equal(2))
+			Expect(pod.Finalizers[0]).To(Equal("finalizers.sigs.k8s.io/testfinalizer2"))
+			Expect(pod.Finalizers[1]).To(Equal("finalizers.sigs.k8s.io/testfinalizer3"))
+
+			// test for result as true, and non-nil error
+			f.result.Updated = true
+			f.result.StatusUpdated = true
+			f.err = fmt.Errorf("finalizer failed")
+			err = finalizers.Register("finalizers.sigs.k8s.io/testfinalizer3", f)
+			Expect(err).To(BeNil())
+
+			result, err = finalizers.Finalize(context.TODO(), pod)
+			Expect(err).ToNot(BeNil())
+			Expect(err.Error()).To(ContainSubstring("finalizer failed"))
+			Expect(result.Updated).To(BeTrue())
+			Expect(result.StatusUpdated).To(BeTrue())
+			Expect(len(pod.Finalizers)).To(Equal(2))
+			Expect(pod.Finalizers[0]).To(Equal("finalizers.sigs.k8s.io/testfinalizer2"))
+			Expect(pod.Finalizers[1]).To(Equal("finalizers.sigs.k8s.io/testfinalizer3"))
+		})
+	})
+})

pkg/finalizer/types.go

@@ -0,0 +1,42 @@
+/*
+Copyright 2021 The Kubernetes Authors.
+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.
+*/
+
+package finalizer
+
+import (
+	"context"
+
+	"sigs.k8s.io/controller-runtime/pkg/client"
+)
+
+// Registerer holds Register that will check if a key is already registered
+// and error out and it does; and if not registered, it will add the finalizer
+// to the finalizers map as the value for the provided key
+type Registerer interface {
+	Register(key string, f Finalizer) error
+}
+
+// Finalizer holds Finalize that will add/remove a finalizer based on the
+// deletion timestamp being set and return an indication of whether the
+// obj needs an update or not
+type Finalizer interface {
+	Finalize(context.Context, client.Object) (Result, error)
+}
+
+// Finalizers implements Registerer and Finalizer to finalize all registered
+// finalizers if the provided object has a deletion timestamp or set all
+// registered finalizers if it does not
+type Finalizers interface {
+	Registerer
+	Finalizer
+}