finalizer

package
v0.15.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 9, 2026 License: Apache-2.0 Imports: 16 Imported by: 0

Documentation

Overview

Package finalizer provides utilities for managing Kubernetes finalizers in controller applications.

Finalizer adds and removes a finalizer with a server-side apply that includes the uid of the object, so it cannot recreate a deleted object. Use it for new code.

GetAddFunc and GetRemoveFunc are deprecated. They use get-modify-write and write the complete object back, so they drop fields that the Go type does not model.

The SetFinalizerHandler provides a handler that automatically adds finalizers to objects that don't already have them, excluding objects with deletion timestamps.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AddFunc

type AddFunc[K component.KubeObject] func(ctx context.Context, nn types.NamespacedName) (K, error)

func GetAddFunc deprecated

func GetAddFunc[K component.KubeObject](client dynamic.Interface, gvr schema.GroupVersionResource, finalizer, fieldManager string) AddFunc[K]

GetAddFunc returns a function that does a get-modify-write instead of an apply, so that it can't accidentally re-create a deleted object (apply does an upsert).

Deprecated: Use Finalizer.Add.

Example
package main

import (
	"context"
	"fmt"

	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
	"k8s.io/apimachinery/pkg/apis/meta/v1/unstructured"
	"k8s.io/apimachinery/pkg/runtime"
	"k8s.io/apimachinery/pkg/runtime/schema"
	"k8s.io/apimachinery/pkg/types"
	"k8s.io/client-go/dynamic/fake"

	"github.com/authzed/controller-idioms/finalizer"
)

func main() {
	ctx, cancel := context.WithCancel(context.Background())
	defer cancel()

	// Create a test object without a finalizer
	testObj := &unstructured.Unstructured{
		Object: map[string]interface{}{
			"apiVersion": "example.com/v1",
			"kind":       "MyObject",
			"metadata": map[string]interface{}{
				"name":      "test-object",
				"namespace": "default",
			},
		},
	}

	// Create a fake dynamic client with the test object
	scheme := runtime.NewScheme()
	dynamicClient := fake.NewSimpleDynamicClient(scheme, testObj)

	// Define the GVR for our resource
	gvr := schema.GroupVersionResource{
		Group:    "example.com",
		Version:  "v1",
		Resource: "myobjects",
	}

	// Create an add function for finalizers
	addFunc := finalizer.GetAddFunc[*metav1.PartialObjectMetadata]( //nolint:staticcheck // example of a deprecated function
		dynamicClient,
		gvr,
		"my-controller.example.com/finalizer",
		"my-controller",
	)

	// Use the function to add a finalizer
	result, err := addFunc(ctx, types.NamespacedName{
		Name:      "test-object",
		Namespace: "default",
	})
	if err != nil {
		fmt.Printf("Error adding finalizer: %v\n", err)
		return
	}

	fmt.Printf("Finalizer added: %v\n", len(result.GetFinalizers()) > 0)
	fmt.Printf("Finalizer name: %s\n", result.GetFinalizers()[0])

}
Output:
Finalizer added: true
Finalizer name: my-controller.example.com/finalizer
Example
ctx, cancel := context.WithCancel(context.Background())
defer cancel()

// Create a test object without a finalizer
testObj := &unstructured.Unstructured{
	Object: map[string]interface{}{
		"apiVersion": "example.com/v1",
		"kind":       "MyObject",
		"metadata": map[string]interface{}{
			"name":      "my-object",
			"namespace": "default",
		},
	},
}

// Create a fake dynamic client with a basic scheme
scheme := runtime.NewScheme()
dynamicClient := fake.NewSimpleDynamicClient(scheme, testObj)

// Define the GVR for our resource
gvr := schema.GroupVersionResource{
	Group:    "example.com",
	Version:  "v1",
	Resource: "myobjects",
}

// Create an add function for finalizers
addFunc := GetAddFunc[*metav1.PartialObjectMetadata](
	dynamicClient,
	gvr,
	"my-controller.example.com/finalizer",
	"my-controller",
)

// Use the function to add a finalizer
result, err := addFunc(ctx, types.NamespacedName{
	Name:      "my-object",
	Namespace: "default",
})
if err != nil {
	fmt.Printf("Error: %v", err)
	return
}

fmt.Printf("Has finalizer: %v", len(result.GetFinalizers()) > 0)
Output:
Has finalizer: true
Example (AlreadyHasFinalizer)
package main

import (
	"context"
	"fmt"

	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
	"k8s.io/apimachinery/pkg/apis/meta/v1/unstructured"
	"k8s.io/apimachinery/pkg/runtime"
	"k8s.io/apimachinery/pkg/runtime/schema"
	"k8s.io/apimachinery/pkg/types"
	"k8s.io/client-go/dynamic/fake"

	"github.com/authzed/controller-idioms/finalizer"
)

func main() {
	ctx, cancel := context.WithCancel(context.Background())
	defer cancel()

	// Create a test object that already has the finalizer
	testObj := &unstructured.Unstructured{
		Object: map[string]interface{}{
			"apiVersion": "example.com/v1",
			"kind":       "MyObject",
			"metadata": map[string]interface{}{
				"name":      "test-object",
				"namespace": "default",
				"finalizers": []interface{}{
					"my-controller.example.com/finalizer",
				},
			},
		},
	}

	// Create a fake dynamic client with the test object
	scheme := runtime.NewScheme()
	dynamicClient := fake.NewSimpleDynamicClient(scheme, testObj)

	// Define the GVR for our resource
	gvr := schema.GroupVersionResource{
		Group:    "example.com",
		Version:  "v1",
		Resource: "myobjects",
	}

	// Create an add function for finalizers
	addFunc := finalizer.GetAddFunc[*metav1.PartialObjectMetadata]( //nolint:staticcheck // example of a deprecated function
		dynamicClient,
		gvr,
		"my-controller.example.com/finalizer",
		"my-controller",
	)

	// Use the function - it should be a no-op since finalizer already exists
	result, err := addFunc(ctx, types.NamespacedName{
		Name:      "test-object",
		Namespace: "default",
	})
	if err != nil {
		fmt.Printf("Error: %v\n", err)
		return
	}

	fmt.Printf("Finalizer count: %d\n", len(result.GetFinalizers()))
	fmt.Printf("Still has finalizer: %v\n", result.GetFinalizers()[0] == "my-controller.example.com/finalizer")

}
Output:
Finalizer count: 1
Still has finalizer: true

type ApplyAddFunc added in v0.15.0

type ApplyAddFunc[K component.KubeObject] func(ctx context.Context, obj K) (K, error)

ApplyAddFunc adds a finalizer to obj.

type FallbackFunc added in v0.15.0

type FallbackFunc[K component.KubeObject] func(ctx context.Context, obj K, owners []string)

FallbackFunc is called when Remove uses a JSON patch because other field managers also own the finalizer. owners are the names of those managers.

type Finalizer added in v0.15.0

type Finalizer[K component.KubeObject] struct {
	// contains filtered or unexported fields
}

Finalizer adds and removes one finalizer with server-side apply. Its field manager is "finalizer:" followed by the finalizer name, so each finalizer has its own manager.

func New added in v0.15.0

New returns a Finalizer for objects of the resource gvr, whose kind is gvk.

func (*Finalizer[K]) Add added in v0.15.0

func (f *Finalizer[K]) Add(ctx context.Context, obj K) (K, error)

Add adds the finalizer to obj. It does nothing if obj already has the finalizer or is being deleted. If the object is gone, Add returns NotFound.

func (*Finalizer[K]) FieldManager added in v0.15.0

func (f *Finalizer[K]) FieldManager() string

FieldManager returns the field manager name of the Finalizer.

func (*Finalizer[K]) Name added in v0.15.0

func (f *Finalizer[K]) Name() string

Name returns the finalizer name.

func (*Finalizer[K]) Remove added in v0.15.0

func (f *Finalizer[K]) Remove(ctx context.Context, obj K) (K, error)

Remove removes the finalizer from obj if obj is being deleted.

Remove first applies an empty list of finalizers. This releases the finalizer if Add added it. An apply cannot remove a finalizer that a different manager also owns, for example one added with an Update by GetAddFunc or by a different controller. If the finalizer is still present, Remove logs the other owners, calls the FallbackFunc, and removes the finalizer with a JSON patch. The patch tests the uid and the position of the finalizer before it removes the entry.

type Option added in v0.15.0

type Option[K component.KubeObject] func(*Finalizer[K])

Option configures a Finalizer.

func WithFallbackFunc added in v0.15.0

func WithFallbackFunc[K component.KubeObject](fn FallbackFunc[K]) Option[K]

WithFallbackFunc sets a function that Remove calls each time it uses the JSON patch. Use it to count finalizers that are still owned by an Update or by a different controller.

type RemoveFunc

type RemoveFunc[K component.KubeObject] func(ctx context.Context, nn types.NamespacedName) (K, error)

func GetRemoveFunc deprecated

func GetRemoveFunc[K component.KubeObject](client dynamic.Interface, gvr schema.GroupVersionResource, finalizer, fieldManager string) RemoveFunc[K]

GetRemoveFunc returns a function that does a get-modify-write instead of an apply. Unlike when adding, this won't be called in cases that could potentially re-create a deleted object, but we do it this way so that the field manager operation matches what created the finalizer (`Update`).

Deprecated: Use Finalizer.Remove.

Example
package main

import (
	"context"
	"fmt"

	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
	"k8s.io/apimachinery/pkg/apis/meta/v1/unstructured"
	"k8s.io/apimachinery/pkg/runtime"
	"k8s.io/apimachinery/pkg/runtime/schema"
	"k8s.io/apimachinery/pkg/types"
	"k8s.io/client-go/dynamic/fake"

	"github.com/authzed/controller-idioms/finalizer"
)

func main() {
	ctx, cancel := context.WithCancel(context.Background())
	defer cancel()

	now := metav1.Now()

	// Create a test object with a finalizer and deletion timestamp
	testObj := &unstructured.Unstructured{
		Object: map[string]interface{}{
			"apiVersion": "example.com/v1",
			"kind":       "MyObject",
			"metadata": map[string]interface{}{
				"name":      "test-object",
				"namespace": "default",
				"finalizers": []interface{}{
					"my-controller.example.com/finalizer",
				},
				"deletionTimestamp": now.Format("2006-01-02T15:04:05Z"),
			},
		},
	}

	// Create a fake dynamic client with the test object
	scheme := runtime.NewScheme()
	dynamicClient := fake.NewSimpleDynamicClient(scheme, testObj)

	// Define the GVR for our resource
	gvr := schema.GroupVersionResource{
		Group:    "example.com",
		Version:  "v1",
		Resource: "myobjects",
	}

	// Create a remove function for finalizers
	removeFunc := finalizer.GetRemoveFunc[*metav1.PartialObjectMetadata]( //nolint:staticcheck // example of a deprecated function
		dynamicClient,
		gvr,
		"my-controller.example.com/finalizer",
		"my-controller",
	)

	// Use the function to remove a finalizer
	result, err := removeFunc(ctx, types.NamespacedName{
		Name:      "test-object",
		Namespace: "default",
	})
	if err != nil {
		fmt.Printf("Error removing finalizer: %v\n", err)
		return
	}

	fmt.Printf("Finalizer removed: %v\n", len(result.GetFinalizers()) == 0)
	fmt.Printf("Has deletion timestamp: %v\n", result.GetDeletionTimestamp() != nil)

}
Output:
Finalizer removed: true
Has deletion timestamp: true
Example
ctx, cancel := context.WithCancel(context.Background())
defer cancel()

now := metav1.Now()

// Create a test object with a finalizer and deletion timestamp
testObj := &unstructured.Unstructured{
	Object: map[string]interface{}{
		"apiVersion": "example.com/v1",
		"kind":       "MyObject",
		"metadata": map[string]interface{}{
			"name":      "my-object",
			"namespace": "default",
			"finalizers": []interface{}{
				"my-controller.example.com/finalizer",
			},
			"deletionTimestamp": now.Format("2006-01-02T15:04:05Z"),
		},
	},
}

// Create a fake dynamic client with a basic scheme
scheme := runtime.NewScheme()
dynamicClient := fake.NewSimpleDynamicClient(scheme, testObj)

// Define the GVR for our resource
gvr := schema.GroupVersionResource{
	Group:    "example.com",
	Version:  "v1",
	Resource: "myobjects",
}

// Create a remove function for finalizers
removeFunc := GetRemoveFunc[*metav1.PartialObjectMetadata](
	dynamicClient,
	gvr,
	"my-controller.example.com/finalizer",
	"my-controller",
)

// Use the function to remove a finalizer
result, err := removeFunc(ctx, types.NamespacedName{
	Name:      "my-object",
	Namespace: "default",
})
if err != nil {
	fmt.Printf("Error: %v", err)
	return
}

fmt.Printf("Finalizer removed: %v", len(result.GetFinalizers()) == 0)
Output:
Finalizer removed: true

type SetFinalizerHandler

type SetFinalizerHandler[K component.KubeObject] struct {
	FinalizeableObjectCtxKey ctxKey[K]
	Finalizer                string
	// AddFinalizer adds the finalizer if ApplyFinalizer is not set.
	//
	// Deprecated: Use ApplyFinalizer with Finalizer.Add.
	AddFinalizer AddFunc[K]
	// If ApplyFinalizer is set, the handler uses it instead of AddFinalizer.
	ApplyFinalizer ApplyAddFunc[K]
	RequeueAPIErr  func(context.Context, error)

	Next handler.Handler
}
Example
ctx, cancel := context.WithCancel(context.Background())
defer cancel()

// Create context key for our object
CtxObject := typedctx.WithDefault[*metav1.PartialObjectMetadata](nil)

// Mock object without finalizer
obj := &metav1.PartialObjectMetadata{
	ObjectMeta: metav1.ObjectMeta{
		Name:      "my-object",
		Namespace: "default",
	},
}

// Add object to context
ctx = CtxObject.WithValue(ctx, obj)

// Create the handler
handler := &SetFinalizerHandler[*metav1.PartialObjectMetadata]{
	FinalizeableObjectCtxKey: CtxObject,
	Finalizer:                "my-controller.example.com/finalizer",
	AddFinalizer: func(_ context.Context, nn types.NamespacedName) (*metav1.PartialObjectMetadata, error) {
		// Mock successful finalizer addition
		return &metav1.PartialObjectMetadata{
			ObjectMeta: metav1.ObjectMeta{
				Name:       nn.Name,
				Namespace:  nn.Namespace,
				Finalizers: []string{"my-controller.example.com/finalizer"},
			},
		}, nil
	},
	RequeueAPIErr: func(_ context.Context, err error) {
		fmt.Printf("Requeue due to error: %v", err)
	},
	Next: handler.NewHandlerFromFunc(func(_ context.Context) {
		fmt.Println("Processing next handler")
	}, "next"),
}

// Execute the handler
handler.Handle(ctx)
Output:
Processing next handler

func (*SetFinalizerHandler[K]) Handle

func (s *SetFinalizerHandler[K]) Handle(ctx context.Context)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL