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
func New[K component.KubeObject](client dynamic.Interface, gvr schema.GroupVersionResource, gvk schema.GroupVersionKind, name string, opts ...Option[K]) *Finalizer[K]
New returns a Finalizer for objects of the resource gvr, whose kind is gvk.
func (*Finalizer[K]) Add ¶ added in v0.15.0
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
FieldManager returns the field manager name of the Finalizer.
func (*Finalizer[K]) Remove ¶ added in v0.15.0
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)