From 26b242fe2dafcf74ab79bc7f0e7e271420677ce6 Mon Sep 17 00:00:00 2001 From: ecordell Date: Mon, 9 Nov 2026 08:59:17 -0500 Subject: [PATCH] finalizer,metaapply: manage finalizers with server-side apply metaapply applies metadata to an existing object. Each apply includes the uid, so it cannot create an object. Each Applier has its own field manager. finalizer.Finalizer uses metaapply to add and remove one finalizer. An apply cannot remove a finalizer that a different manager also owns. In this case, Remove uses a JSON patch. SetFinalizerHandler uses ApplyFinalizer if it is set. Its AddFinalizer field, GetAddFunc, and GetRemoveFunc are deprecated. --- README.md | 2 + finalizer/apply.go | 171 +++++++++++++++++++++++++ finalizer/apply_e2e_test.go | 218 ++++++++++++++++++++++++++++++++ finalizer/finalizer.go | 15 ++- finalizer/finalizer_test.go | 6 +- finalizer/set_finalizer.go | 17 ++- finalizer/set_finalizer_test.go | 32 +++++ metaapply/metaapply.go | 115 +++++++++++++++++ metaapply/metaapply_e2e_test.go | 114 +++++++++++++++++ metaapply/metaapply_test.go | 47 +++++++ 10 files changed, 727 insertions(+), 10 deletions(-) create mode 100644 finalizer/apply.go create mode 100644 finalizer/apply_e2e_test.go create mode 100644 metaapply/metaapply.go create mode 100644 metaapply/metaapply_e2e_test.go create mode 100644 metaapply/metaapply_test.go diff --git a/README.md b/README.md index 56920ef..798817c 100644 --- a/README.md +++ b/README.md @@ -23,6 +23,7 @@ Available idioms include: - **[component]**: manage and aggregate resources that are created on behalf of another resource - **[fileinformer]**: an InformerFactory that watches local files typically for loading config without restarting - **[hash]**: hashing resources to detect modifications +- **[metaapply]**: apply metadata changes (labels, annotations, finalizers) to existing objects without recreating them or dropping fields - **[metrics]**: metrics for resources that implement standard `metav1.Condition` arrays - **[pause]**: handler that allows users stop the controller reconciling a particular resource without stopping the controller - **[static]**: controller for "static" resources that should always exist on startup @@ -32,6 +33,7 @@ Available idioms include: [component]: https://pkg.go.dev/github.com/authzed/controller-idioms/component [fileinformer]: https://pkg.go.dev/github.com/authzed/controller-idioms/fileinformer [hash]: https://pkg.go.dev/github.com/authzed/controller-idioms/hash +[metaapply]: https://pkg.go.dev/github.com/authzed/controller-idioms/metaapply [metrics]: https://pkg.go.dev/github.com/authzed/controller-idioms/metrics [pause]: https://pkg.go.dev/github.com/authzed/controller-idioms/pause [static]: https://pkg.go.dev/github.com/authzed/controller-idioms/static diff --git a/finalizer/apply.go b/finalizer/apply.go new file mode 100644 index 0000000..e86c54a --- /dev/null +++ b/finalizer/apply.go @@ -0,0 +1,171 @@ +package finalizer + +import ( + "context" + "encoding/json" + "fmt" + "slices" + + "github.com/go-logr/logr" + metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" + "k8s.io/apimachinery/pkg/apis/meta/v1/unstructured" + "k8s.io/apimachinery/pkg/runtime/schema" + "k8s.io/apimachinery/pkg/types" + "k8s.io/client-go/dynamic" + + "github.com/authzed/controller-idioms/component" + "github.com/authzed/controller-idioms/metaapply" + "github.com/authzed/controller-idioms/typed" +) + +// ApplyAddFunc adds a finalizer to obj. +type ApplyAddFunc[K component.KubeObject] func(ctx context.Context, obj K) (K, error) + +// 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 FallbackFunc[K component.KubeObject] func(ctx context.Context, obj K, owners []string) + +// 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. +type Finalizer[K component.KubeObject] struct { + client dynamic.Interface + gvr schema.GroupVersionResource + name string + meta *metaapply.Applier + onFallback FallbackFunc[K] +} + +// Option configures a Finalizer. +type Option[K component.KubeObject] func(*Finalizer[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. +func WithFallbackFunc[K component.KubeObject](fn FallbackFunc[K]) Option[K] { + return func(f *Finalizer[K]) { f.onFallback = fn } +} + +// New returns a Finalizer for objects of the resource gvr, whose kind is gvk. +func New[K component.KubeObject](client dynamic.Interface, gvr schema.GroupVersionResource, gvk schema.GroupVersionKind, name string, opts ...Option[K]) *Finalizer[K] { + f := &Finalizer[K]{ + client: client, + gvr: gvr, + name: name, + meta: metaapply.New(client, gvr, gvk, "finalizer:"+name), + } + for _, opt := range opts { + opt(f) + } + return f +} + +// Name returns the finalizer name. +func (f *Finalizer[K]) Name() string { + return f.name +} + +// FieldManager returns the field manager name of the Finalizer. +func (f *Finalizer[K]) FieldManager() string { + return f.meta.FieldManager() +} + +// 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 (f *Finalizer[K]) Add(ctx context.Context, obj K) (K, error) { + if slices.Contains(obj.GetFinalizers(), f.name) || obj.GetDeletionTimestamp() != nil { + return obj, nil + } + return f.applyFinalizers(ctx, obj, []string{f.name}) +} + +// 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. +func (f *Finalizer[K]) Remove(ctx context.Context, obj K) (K, error) { + var nilObj K + if !slices.Contains(obj.GetFinalizers(), f.name) || obj.GetDeletionTimestamp() == nil { + return obj, nil + } + applied, err := f.applyFinalizers(ctx, obj, []string{}) + if err != nil { + return nilObj, err + } + idx := slices.Index(applied.GetFinalizers(), f.name) + if idx == -1 { + return applied, nil + } + + owners := finalizerOwners(applied.GetManagedFields(), f.name) + logr.FromContextOrDiscard(ctx).V(2).Info("removing finalizer with a JSON patch because other field managers own it", + "finalizer", f.name, "object", types.NamespacedName{Namespace: obj.GetNamespace(), Name: obj.GetName()}, "owners", owners) + if f.onFallback != nil { + f.onFallback(ctx, obj, owners) + } + + patch, err := removeFinalizerPatch(obj.GetUID(), idx, f.name) + if err != nil { + return nilObj, err + } + u, err := f.client.Resource(f.gvr).Namespace(obj.GetNamespace()).Patch(ctx, obj.GetName(), types.JSONPatchType, patch, metav1.PatchOptions{FieldManager: f.FieldManager()}) + if err != nil { + return nilObj, err + } + return typed.UnstructuredObjToTypedObj[K](u) +} + +func (f *Finalizer[K]) applyFinalizers(ctx context.Context, obj K, finalizers []string) (K, error) { + var nilObj K + u, err := f.meta.Apply(ctx, obj, func(body *unstructured.Unstructured) { + // An empty list releases the finalizer. A nil list would omit the field. + body.SetFinalizers(finalizers) + }) + if err != nil { + return nilObj, err + } + return typed.UnstructuredObjToTypedObj[K](u) +} + +// finalizerOwners returns the field managers that own finalizer. +func finalizerOwners(entries []metav1.ManagedFieldsEntry, finalizer string) []string { + quoted, err := json.Marshal(finalizer) + if err != nil { + return nil + } + key := "v:" + string(quoted) + var owners []string + for _, entry := range entries { + if entry.FieldsV1 == nil { + continue + } + var fields struct { + Metadata struct { + Finalizers map[string]json.RawMessage `json:"f:finalizers"` + } `json:"f:metadata"` + } + if err := json.Unmarshal(entry.FieldsV1.GetRawBytes(), &fields); err != nil { + continue + } + if _, ok := fields.Metadata.Finalizers[key]; ok { + owners = append(owners, entry.Manager) + } + } + return owners +} + +// removeFinalizerPatch returns a JSON patch that removes the entry at idx. The +// patch fails if the uid changed or if the entry at idx is not finalizer. +func removeFinalizerPatch(uid types.UID, idx int, finalizer string) ([]byte, error) { + path := fmt.Sprintf("/metadata/finalizers/%d", idx) + return json.Marshal([]map[string]any{ + {"op": "test", "path": "/metadata/uid", "value": uid}, + {"op": "test", "path": path, "value": finalizer}, + {"op": "remove", "path": path}, + }) +} diff --git a/finalizer/apply_e2e_test.go b/finalizer/apply_e2e_test.go new file mode 100644 index 0000000..d7a7dae --- /dev/null +++ b/finalizer/apply_e2e_test.go @@ -0,0 +1,218 @@ +//go:build e2e + +package finalizer_test + +import ( + "context" + "testing" + + "github.com/stretchr/testify/require" + corev1 "k8s.io/api/core/v1" + k8serrors "k8s.io/apimachinery/pkg/api/errors" + 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/cli-runtime/pkg/genericclioptions" + "k8s.io/client-go/dynamic" + cmdutil "k8s.io/kubectl/pkg/cmd/util" + "k8s.io/utils/ptr" + + "github.com/authzed/controller-idioms/finalizer" + "github.com/authzed/controller-idioms/typed" +) + +const ( + testFinalizer = "example.com/finalizer" + otherFinalizer = "example.com/other" +) + +var ( + configMapGVR = schema.GroupVersionResource{Version: "v1", Resource: "configmaps"} + configMapGVK = schema.GroupVersionKind{Version: "v1", Kind: "ConfigMap"} +) + +func e2eClient(t *testing.T) dynamic.Interface { + t.Helper() + opts := genericclioptions.NewConfigFlags(true) + opts.KubeConfig = ptr.To("../controller-idioms-e2e.kubeconfig") + client, err := cmdutil.NewFactory(opts).DynamicClient() + require.NoError(t, err) + return client +} + +// createConfigMap creates a ConfigMap with data and the given finalizers. The +// data shows if a write drops fields. +func createConfigMap(t *testing.T, client dynamic.Interface, finalizers ...string) *corev1.ConfigMap { + t.Helper() + cm := &corev1.ConfigMap{ + TypeMeta: metav1.TypeMeta{APIVersion: "v1", Kind: "ConfigMap"}, + ObjectMeta: metav1.ObjectMeta{GenerateName: "finalizer-", Namespace: "default", Finalizers: finalizers}, + Data: map[string]string{"key": "value"}, + } + u, err := runtime.DefaultUnstructuredConverter.ToUnstructured(cm) + require.NoError(t, err) + created, err := client.Resource(configMapGVR).Namespace("default").Create(t.Context(), &unstructured.Unstructured{Object: u}, metav1.CreateOptions{FieldManager: "creator"}) + require.NoError(t, err) + t.Cleanup(func() { + // Remove all finalizers so that a failed test does not leave the object. + _, _ = client.Resource(configMapGVR).Namespace("default").Patch(context.Background(), created.GetName(), types.MergePatchType, []byte(`{"metadata":{"finalizers":null}}`), metav1.PatchOptions{}) + _ = client.Resource(configMapGVR).Namespace("default").Delete(context.Background(), created.GetName(), metav1.DeleteOptions{}) + }) + out, err := typed.UnstructuredObjToTypedObj[*corev1.ConfigMap](created) + require.NoError(t, err) + return out +} + +func getConfigMap(t *testing.T, client dynamic.Interface, name string) (*corev1.ConfigMap, error) { + t.Helper() + u, err := client.Resource(configMapGVR).Namespace("default").Get(t.Context(), name, metav1.GetOptions{}) + if err != nil { + return nil, err + } + return typed.UnstructuredObjToTypedObj[*corev1.ConfigMap](u) +} + +func deleteConfigMap(t *testing.T, client dynamic.Interface, name string) *corev1.ConfigMap { + t.Helper() + require.NoError(t, client.Resource(configMapGVR).Namespace("default").Delete(t.Context(), name, metav1.DeleteOptions{})) + cm, err := getConfigMap(t, client, name) + require.NoError(t, err, "a finalizer keeps the object") + require.NotNil(t, cm.DeletionTimestamp) + return cm +} + +func TestFinalizer(t *testing.T) { + client := e2eClient(t) + + // newFinalizer returns a Finalizer that records the owners passed to each + // fallback. + newFinalizer := func() (*finalizer.Finalizer[*corev1.ConfigMap], *[][]string) { + var fallbacks [][]string + f := finalizer.New[*corev1.ConfigMap](client, configMapGVR, configMapGVK, testFinalizer, + finalizer.WithFallbackFunc(func(_ context.Context, _ *corev1.ConfigMap, owners []string) { + fallbacks = append(fallbacks, owners) + })) + return f, &fallbacks + } + + t.Run("added and removed by apply", func(t *testing.T) { + f, fallbacks := newFinalizer() + cm := createConfigMap(t, client) + + added, err := f.Add(t.Context(), cm) + require.NoError(t, err) + require.Equal(t, []string{testFinalizer}, added.Finalizers) + require.Equal(t, map[string]string{"key": "value"}, added.Data) + + terminating := deleteConfigMap(t, client, cm.Name) + _, err = f.Remove(t.Context(), terminating) + require.NoError(t, err) + _, err = getConfigMap(t, client, cm.Name) + require.True(t, k8serrors.IsNotFound(err), "releasing the only finalizer lets the delete finish") + require.Empty(t, *fallbacks, "the apply releases its own finalizer") + }) + + t.Run("keeps fields the object type does not model", func(t *testing.T) { + // GetAddFunc writes the complete object as K. With a metadata-only K, it + // drops the data. The apply sends only the finalizers. + cm := createConfigMap(t, client) + metaOnly := finalizer.New[*metav1.PartialObjectMetadata](client, configMapGVR, configMapGVK, testFinalizer) + + _, err := metaOnly.Add(t.Context(), &metav1.PartialObjectMetadata{ObjectMeta: cm.ObjectMeta}) + require.NoError(t, err) + live, err := getConfigMap(t, client, cm.Name) + require.NoError(t, err) + require.Equal(t, []string{testFinalizer}, live.Finalizers) + require.Equal(t, map[string]string{"key": "value"}, live.Data) + }) + + t.Run("removes a finalizer added by GetAddFunc", func(t *testing.T) { + f, fallbacks := newFinalizer() + cm := createConfigMap(t, client) + _, err := finalizer.GetAddFunc[*corev1.ConfigMap](client, configMapGVR, testFinalizer, "legacy")(t.Context(), types.NamespacedName{Namespace: cm.Namespace, Name: cm.Name}) //nolint:staticcheck // tests objects from the deprecated function + require.NoError(t, err) + + terminating := deleteConfigMap(t, client, cm.Name) + _, err = f.Remove(t.Context(), terminating) + require.NoError(t, err) + _, err = getConfigMap(t, client, cm.Name) + require.True(t, k8serrors.IsNotFound(err)) + require.Equal(t, [][]string{{"legacy"}}, *fallbacks, "the Update owner is reported") + }) + + t.Run("removes a finalizer another manager added, and only that one", func(t *testing.T) { + f, fallbacks := newFinalizer() + cm := createConfigMap(t, client, otherFinalizer, testFinalizer) + + terminating := deleteConfigMap(t, client, cm.Name) + removed, err := f.Remove(t.Context(), terminating) + require.NoError(t, err) + require.Equal(t, []string{otherFinalizer}, removed.Finalizers) + require.Equal(t, map[string]string{"key": "value"}, removed.Data) + require.Equal(t, [][]string{{"creator"}}, *fallbacks) + }) + + t.Run("GetRemoveFunc removes a finalizer added by Add", func(t *testing.T) { + // A controller that rolls back to GetRemoveFunc must still release + // finalizers that Add owns with an Apply entry. + f, _ := newFinalizer() + cm := createConfigMap(t, client) + _, err := f.Add(t.Context(), cm) + require.NoError(t, err) + + deleteConfigMap(t, client, cm.Name) + _, err = finalizer.GetRemoveFunc[*corev1.ConfigMap](client, configMapGVR, testFinalizer, "legacy")(t.Context(), types.NamespacedName{Namespace: cm.Namespace, Name: cm.Name}) //nolint:staticcheck // tests objects from the deprecated function + require.NoError(t, err) + _, err = getConfigMap(t, client, cm.Name) + require.True(t, k8serrors.IsNotFound(err)) + }) + + t.Run("does not remove from an object that is not being deleted", func(t *testing.T) { + f, _ := newFinalizer() + cm := createConfigMap(t, client, testFinalizer) + + _, err := f.Remove(t.Context(), cm) + require.NoError(t, err) + live, err := getConfigMap(t, client, cm.Name) + require.NoError(t, err) + require.Equal(t, []string{testFinalizer}, live.Finalizers) + }) + + t.Run("does not recreate an object that is gone", func(t *testing.T) { + f, _ := newFinalizer() + cm := createConfigMap(t, client) + require.NoError(t, client.Resource(configMapGVR).Namespace("default").Delete(t.Context(), cm.Name, metav1.DeleteOptions{})) + + _, err := f.Add(t.Context(), cm) + require.True(t, k8serrors.IsNotFound(err), "got %v", err) + _, err = getConfigMap(t, client, cm.Name) + require.True(t, k8serrors.IsNotFound(err), "the apply must not upsert") + }) + + t.Run("does not change an object replaced under the same name", func(t *testing.T) { + f, _ := newFinalizer() + stale := createConfigMap(t, client, testFinalizer) + terminating := deleteConfigMap(t, client, stale.Name) + _, err := client.Resource(configMapGVR).Namespace("default").Patch(t.Context(), stale.Name, types.MergePatchType, []byte(`{"metadata":{"finalizers":null}}`), metav1.PatchOptions{}) + require.NoError(t, err) + + replacement := &corev1.ConfigMap{ + TypeMeta: metav1.TypeMeta{APIVersion: "v1", Kind: "ConfigMap"}, + ObjectMeta: metav1.ObjectMeta{Name: stale.Name, Namespace: "default", Finalizers: []string{testFinalizer}}, + } + u, err := runtime.DefaultUnstructuredConverter.ToUnstructured(replacement) + require.NoError(t, err) + _, err = client.Resource(configMapGVR).Namespace("default").Create(t.Context(), &unstructured.Unstructured{Object: u}, metav1.CreateOptions{}) + require.NoError(t, err) + live := deleteConfigMap(t, client, stale.Name) + + _, err = f.Remove(t.Context(), terminating) + require.Error(t, err, "the stale uid must not match the replacement") + after, err := getConfigMap(t, client, stale.Name) + require.NoError(t, err) + require.Equal(t, live.UID, after.UID) + require.Equal(t, []string{testFinalizer}, after.Finalizers, "the replacement keeps its finalizer") + }) +} diff --git a/finalizer/finalizer.go b/finalizer/finalizer.go index 9d8d64a..1583d76 100644 --- a/finalizer/finalizer.go +++ b/finalizer/finalizer.go @@ -1,10 +1,13 @@ // Package finalizer provides utilities for managing Kubernetes finalizers in // controller applications. // -// The core functions GetAddFunc and GetRemoveFunc return functions that can -// add or remove finalizers from Kubernetes objects. These use get-modify-write -// instead of apply/patch operations to ensure they cannot recreate objects -// that have been marked for deletion. +// 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 @@ -33,6 +36,8 @@ type ( // 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. func GetAddFunc[K component.KubeObject](client dynamic.Interface, gvr schema.GroupVersionResource, finalizer, fieldManager string) AddFunc[K] { return func(ctx context.Context, nn types.NamespacedName) (K, error) { // get latest object @@ -72,6 +77,8 @@ func GetAddFunc[K component.KubeObject](client dynamic.Interface, gvr schema.Gro // 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. func GetRemoveFunc[K component.KubeObject](client dynamic.Interface, gvr schema.GroupVersionResource, finalizer, fieldManager string) RemoveFunc[K] { return func(ctx context.Context, nn types.NamespacedName) (K, error) { // get latest object diff --git a/finalizer/finalizer_test.go b/finalizer/finalizer_test.go index 562ee1e..02a943e 100644 --- a/finalizer/finalizer_test.go +++ b/finalizer/finalizer_test.go @@ -42,7 +42,7 @@ func ExampleGetAddFunc() { } // Create an add function for finalizers - addFunc := finalizer.GetAddFunc[*metav1.PartialObjectMetadata]( + addFunc := finalizer.GetAddFunc[*metav1.PartialObjectMetadata]( //nolint:staticcheck // example of a deprecated function dynamicClient, gvr, "my-controller.example.com/finalizer", @@ -100,7 +100,7 @@ func ExampleGetRemoveFunc() { } // Create a remove function for finalizers - removeFunc := finalizer.GetRemoveFunc[*metav1.PartialObjectMetadata]( + removeFunc := finalizer.GetRemoveFunc[*metav1.PartialObjectMetadata]( //nolint:staticcheck // example of a deprecated function dynamicClient, gvr, "my-controller.example.com/finalizer", @@ -155,7 +155,7 @@ func ExampleGetAddFunc_alreadyHasFinalizer() { } // Create an add function for finalizers - addFunc := finalizer.GetAddFunc[*metav1.PartialObjectMetadata]( + addFunc := finalizer.GetAddFunc[*metav1.PartialObjectMetadata]( //nolint:staticcheck // example of a deprecated function dynamicClient, gvr, "my-controller.example.com/finalizer", diff --git a/finalizer/set_finalizer.go b/finalizer/set_finalizer.go index 7577c45..5892d0c 100644 --- a/finalizer/set_finalizer.go +++ b/finalizer/set_finalizer.go @@ -19,8 +19,13 @@ type ctxKey[K component.KubeObject] interface { type SetFinalizerHandler[K component.KubeObject] struct { FinalizeableObjectCtxKey ctxKey[K] Finalizer string - AddFinalizer AddFunc[K] - RequeueAPIErr func(context.Context, error) + // 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 } @@ -28,7 +33,13 @@ type SetFinalizerHandler[K component.KubeObject] struct { func (s *SetFinalizerHandler[K]) Handle(ctx context.Context) { obj := s.FinalizeableObjectCtxKey.MustValue(ctx) if !slices.Contains(obj.GetFinalizers(), s.Finalizer) && obj.GetDeletionTimestamp() == nil { - db, err := s.AddFinalizer(ctx, types.NamespacedName{Name: obj.GetName(), Namespace: obj.GetNamespace()}) + var db K + var err error + if s.ApplyFinalizer != nil { + db, err = s.ApplyFinalizer(ctx, obj) + } else { + db, err = s.AddFinalizer(ctx, types.NamespacedName{Name: obj.GetName(), Namespace: obj.GetNamespace()}) + } if err != nil { s.RequeueAPIErr(ctx, err) return diff --git a/finalizer/set_finalizer_test.go b/finalizer/set_finalizer_test.go index 0df4a06..52da3c3 100644 --- a/finalizer/set_finalizer_test.go +++ b/finalizer/set_finalizer_test.go @@ -169,6 +169,38 @@ func ExampleSetFinalizerHandler() { // Output: Processing next handler } +func TestSetFinalizerPrefersApplyFinalizer(t *testing.T) { + t.Parallel() + + CtxObject := typedctx.WithDefault[*metav1.PartialObjectMetadata](nil) + obj := &metav1.PartialObjectMetadata{ObjectMeta: metav1.ObjectMeta{Name: "test", Namespace: "test", UID: "uid"}} + applied := &metav1.PartialObjectMetadata{ObjectMeta: metav1.ObjectMeta{Name: "test", Namespace: "test", UID: "uid", Finalizers: []string{"finalizer"}}} + + var received, next *metav1.PartialObjectMetadata + h := &SetFinalizerHandler[*metav1.PartialObjectMetadata]{ + FinalizeableObjectCtxKey: CtxObject, + Finalizer: "finalizer", + AddFinalizer: func(_ context.Context, _ types.NamespacedName) (*metav1.PartialObjectMetadata, error) { + require.Fail(t, "AddFinalizer must not be called when ApplyFinalizer is set") + return nil, nil + }, + ApplyFinalizer: func(_ context.Context, o *metav1.PartialObjectMetadata) (*metav1.PartialObjectMetadata, error) { + received = o + return applied, nil + }, + RequeueAPIErr: func(_ context.Context, err error) { + require.NoError(t, err) + }, + Next: handler.NewHandlerFromFunc(func(ctx context.Context) { + next = CtxObject.MustValue(ctx) + }, "next"), + } + h.Handle(CtxObject.WithValue(t.Context(), obj)) + + require.Same(t, obj, received, "ApplyFinalizer gets the object with its uid") + require.Same(t, applied, next, "the next handler gets the applied object") +} + func TestSetFinalizer(t *testing.T) { t.Parallel() diff --git a/metaapply/metaapply.go b/metaapply/metaapply.go new file mode 100644 index 0000000..07300e8 --- /dev/null +++ b/metaapply/metaapply.go @@ -0,0 +1,115 @@ +// Package metaapply changes the metadata of an existing object with a +// server-side apply. +// +// An Applier writes only metadata, and it includes the uid of the object in +// each apply. Thus an apply cannot create an object, and it cannot change a +// different object with the same name. An Applier also does not write the +// complete object, so it cannot drop fields that a Go type does not model. +// +// Each Applier has its own field manager, which ManagerFor makes from a +// purpose. An apply sets the complete set of fields that its manager owns, so +// a manager that also owns spec fields would lose them. Apply refuses to write +// if the manager owns fields outside metadata. +package metaapply + +import ( + "context" + "crypto/sha256" + "encoding/hex" + "encoding/json" + "errors" + "fmt" + + k8serrors "k8s.io/apimachinery/pkg/api/errors" + metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" + "k8s.io/apimachinery/pkg/apis/meta/v1/unstructured" + metav1validation "k8s.io/apimachinery/pkg/apis/meta/v1/validation" + "k8s.io/apimachinery/pkg/runtime/schema" + "k8s.io/client-go/dynamic" +) + +// maxManagerLength is the longest field manager name that the apiserver +// accepts. +var maxManagerLength = metav1validation.FieldManagerMaxLength + +// ErrOwnsNonMetadata is returned when the field manager of an Applier owns +// fields outside metadata. +var ErrOwnsNonMetadata = errors.New("field manager owns fields outside metadata") + +// ManagerFor returns the field manager name for purpose. A purpose that is too +// long is shortened and given a hash suffix, so that different purposes give +// different names. +func ManagerFor(purpose string) string { + if len(purpose) <= maxManagerLength { + return purpose + } + sum := sha256.Sum256([]byte(purpose)) + suffix := "-" + hex.EncodeToString(sum[:])[:16] + return purpose[:maxManagerLength-len(suffix)] + suffix +} + +// Applier applies metadata to objects of one resource. +type Applier struct { + client dynamic.Interface + gvr schema.GroupVersionResource + gvk schema.GroupVersionKind + manager string +} + +// New returns an Applier for the resource gvr, whose kind is gvk. Its field +// manager is ManagerFor(purpose). Use a different purpose for each set of +// metadata fields. +func New(client dynamic.Interface, gvr schema.GroupVersionResource, gvk schema.GroupVersionKind, purpose string) *Applier { + return &Applier{client: client, gvr: gvr, gvk: gvk, manager: ManagerFor(purpose)} +} + +// FieldManager returns the field manager name of the Applier. +func (a *Applier) FieldManager() string { + return a.manager +} + +// Apply applies the metadata that set writes. The body that set receives +// already has the kind, name, namespace, and uid of obj. Do not change them. +// +// If the object is gone, Apply returns NotFound. If the managed fields of obj +// show that the manager owns fields outside metadata, Apply returns +// ErrOwnsNonMetadata and writes nothing. If obj has no managed fields, Apply +// cannot do this check. +func (a *Applier) Apply(ctx context.Context, obj metav1.Object, set func(body *unstructured.Unstructured)) (*unstructured.Unstructured, error) { + if err := checkOwnsOnlyMetadata(obj.GetManagedFields(), a.manager); err != nil { + return nil, err + } + + body := &unstructured.Unstructured{} + body.SetGroupVersionKind(a.gvk) + body.SetName(obj.GetName()) + body.SetNamespace(obj.GetNamespace()) + body.SetUID(obj.GetUID()) + set(body) + + u, err := a.client.Resource(a.gvr).Namespace(obj.GetNamespace()).Apply(ctx, obj.GetName(), body, metav1.ApplyOptions{FieldManager: a.manager, Force: true}) + // A forced apply of metadata has no field conflicts. A conflict here means + // that the uid does not match because the object does not exist. + if k8serrors.IsConflict(err) { + return nil, k8serrors.NewNotFound(a.gvr.GroupResource(), obj.GetName()) + } + return u, err +} + +func checkOwnsOnlyMetadata(entries []metav1.ManagedFieldsEntry, manager string) error { + for _, entry := range entries { + if entry.Manager != manager || entry.Operation != metav1.ManagedFieldsOperationApply || entry.FieldsV1 == nil { + continue + } + var fields map[string]json.RawMessage + if err := json.Unmarshal(entry.FieldsV1.GetRawBytes(), &fields); err != nil { + return fmt.Errorf("read managed fields of %s: %w", manager, err) + } + for key := range fields { + if key != "f:metadata" && key != "." { + return fmt.Errorf("%w: %s owns %s", ErrOwnsNonMetadata, manager, key) + } + } + } + return nil +} diff --git a/metaapply/metaapply_e2e_test.go b/metaapply/metaapply_e2e_test.go new file mode 100644 index 0000000..92d19af --- /dev/null +++ b/metaapply/metaapply_e2e_test.go @@ -0,0 +1,114 @@ +//go:build e2e + +package metaapply_test + +import ( + "context" + "testing" + + "github.com/stretchr/testify/require" + corev1 "k8s.io/api/core/v1" + k8serrors "k8s.io/apimachinery/pkg/api/errors" + metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" + "k8s.io/apimachinery/pkg/apis/meta/v1/unstructured" + "k8s.io/apimachinery/pkg/runtime/schema" + "k8s.io/cli-runtime/pkg/genericclioptions" + "k8s.io/client-go/dynamic" + cmdutil "k8s.io/kubectl/pkg/cmd/util" + "k8s.io/utils/ptr" + + "github.com/authzed/controller-idioms/metaapply" + "github.com/authzed/controller-idioms/typed" +) + +var ( + configMapGVR = schema.GroupVersionResource{Version: "v1", Resource: "configmaps"} + configMapGVK = schema.GroupVersionKind{Version: "v1", Kind: "ConfigMap"} +) + +func e2eClient(t *testing.T) dynamic.Interface { + t.Helper() + opts := genericclioptions.NewConfigFlags(true) + opts.KubeConfig = ptr.To("../controller-idioms-e2e.kubeconfig") + client, err := cmdutil.NewFactory(opts).DynamicClient() + require.NoError(t, err) + return client +} + +// createConfigMap creates a ConfigMap with data, applied by manager. The data +// shows if a write drops fields. +func createConfigMap(t *testing.T, client dynamic.Interface, name, manager string) *corev1.ConfigMap { + t.Helper() + body := &unstructured.Unstructured{Object: map[string]any{ + "apiVersion": "v1", + "kind": "ConfigMap", + "metadata": map[string]any{"name": name, "namespace": "default"}, + "data": map[string]any{"key": "value"}, + }} + u, err := client.Resource(configMapGVR).Namespace("default").Apply(t.Context(), name, body, metav1.ApplyOptions{FieldManager: manager, Force: true}) + require.NoError(t, err) + t.Cleanup(func() { + _ = client.Resource(configMapGVR).Namespace("default").Delete(context.Background(), name, metav1.DeleteOptions{}) + }) + cm, err := typed.UnstructuredObjToTypedObj[*corev1.ConfigMap](u) + require.NoError(t, err) + return cm +} + +func setLabel(body *unstructured.Unstructured) { + body.SetLabels(map[string]string{"example.com/label": "on"}) +} + +func TestApply(t *testing.T) { + client := e2eClient(t) + + t.Run("applies metadata and keeps other fields", func(t *testing.T) { + cm := createConfigMap(t, client, "metaapply-keeps", "owner") + a := metaapply.New(client, configMapGVR, configMapGVK, "label") + + u, err := a.Apply(t.Context(), cm, setLabel) + require.NoError(t, err) + require.Equal(t, map[string]string{"example.com/label": "on"}, u.GetLabels()) + data, _, err := unstructured.NestedStringMap(u.Object, "data") + require.NoError(t, err) + require.Equal(t, map[string]string{"key": "value"}, data) + }) + + t.Run("refuses when the manager owns fields outside metadata", func(t *testing.T) { + // The manager applied data, so an apply of metadata alone would prune it. + cm := createConfigMap(t, client, "metaapply-refuses", "shared") + a := metaapply.New(client, configMapGVR, configMapGVK, "shared") + + _, err := a.Apply(t.Context(), cm, setLabel) + require.ErrorIs(t, err, metaapply.ErrOwnsNonMetadata) + u, err := client.Resource(configMapGVR).Namespace("default").Get(t.Context(), cm.Name, metav1.GetOptions{}) + require.NoError(t, err) + require.Empty(t, u.GetLabels(), "nothing is written") + }) + + t.Run("does not recreate an object that is gone", func(t *testing.T) { + cm := createConfigMap(t, client, "metaapply-gone", "owner") + require.NoError(t, client.Resource(configMapGVR).Namespace("default").Delete(t.Context(), cm.Name, metav1.DeleteOptions{})) + a := metaapply.New(client, configMapGVR, configMapGVK, "label") + + _, err := a.Apply(t.Context(), cm, setLabel) + require.True(t, k8serrors.IsNotFound(err), "got %v", err) + _, err = client.Resource(configMapGVR).Namespace("default").Get(t.Context(), cm.Name, metav1.GetOptions{}) + require.True(t, k8serrors.IsNotFound(err), "the apply must not upsert") + }) + + t.Run("does not change an object replaced under the same name", func(t *testing.T) { + stale := createConfigMap(t, client, "metaapply-replaced", "owner") + require.NoError(t, client.Resource(configMapGVR).Namespace("default").Delete(t.Context(), stale.Name, metav1.DeleteOptions{})) + replacement := createConfigMap(t, client, stale.Name, "owner") + require.NotEqual(t, stale.UID, replacement.UID) + a := metaapply.New(client, configMapGVR, configMapGVK, "label") + + _, err := a.Apply(t.Context(), stale, setLabel) + require.Error(t, err) + u, err := client.Resource(configMapGVR).Namespace("default").Get(t.Context(), stale.Name, metav1.GetOptions{}) + require.NoError(t, err) + require.Equal(t, replacement.UID, u.GetUID()) + require.Empty(t, u.GetLabels()) + }) +} diff --git a/metaapply/metaapply_test.go b/metaapply/metaapply_test.go new file mode 100644 index 0000000..ae0053a --- /dev/null +++ b/metaapply/metaapply_test.go @@ -0,0 +1,47 @@ +package metaapply + +import ( + "strings" + "testing" + + "github.com/stretchr/testify/require" + metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" +) + +func TestManagerFor(t *testing.T) { + short := "finalizer:example.com/finalizer" + require.Equal(t, short, ManagerFor(short)) + + long := "finalizer:" + strings.Repeat("a", 200) + longer := long + "b" + require.Len(t, ManagerFor(long), maxManagerLength) + require.Len(t, ManagerFor(longer), maxManagerLength) + require.NotEqual(t, ManagerFor(long), ManagerFor(longer), "purposes with a shared prefix get different names") +} + +func TestCheckOwnsOnlyMetadata(t *testing.T) { + entry := func(manager string, op metav1.ManagedFieldsOperationType, fields string) metav1.ManagedFieldsEntry { + return metav1.ManagedFieldsEntry{Manager: manager, Operation: op, FieldsV1: metav1.NewFieldsV1(fields)} + } + for _, tc := range []struct { + name string + entries []metav1.ManagedFieldsEntry + wantErr bool + }{ + {name: "no managed fields"}, + {name: "metadata only", entries: []metav1.ManagedFieldsEntry{entry("m", metav1.ManagedFieldsOperationApply, `{"f:metadata":{"f:labels":{}}}`)}}, + {name: "owns data", entries: []metav1.ManagedFieldsEntry{entry("m", metav1.ManagedFieldsOperationApply, `{"f:data":{"f:key":{}}}`)}, wantErr: true}, + // An Update entry is not changed by an apply, so it cannot lose fields. + {name: "update entry owns data", entries: []metav1.ManagedFieldsEntry{entry("m", metav1.ManagedFieldsOperationUpdate, `{"f:data":{}}`)}}, + {name: "another manager owns data", entries: []metav1.ManagedFieldsEntry{entry("other", metav1.ManagedFieldsOperationApply, `{"f:data":{}}`)}}, + } { + t.Run(tc.name, func(t *testing.T) { + err := checkOwnsOnlyMetadata(tc.entries, "m") + if tc.wantErr { + require.ErrorIs(t, err, ErrOwnsNonMetadata) + return + } + require.NoError(t, err) + }) + } +}