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) + }) + } +}