feat: support for krateo.io/gracefully-paused annotation

Author: matteogastaldello

go.mod

@@ -20,7 +20,6 @@ require (
 	k8s.io/apimachinery v0.33.3
 	k8s.io/cli-runtime v0.33.3
 	k8s.io/client-go v0.33.3
-	k8s.io/utils v0.0.0-20241104100929-3ea5e8cea738
 	sigs.k8s.io/e2e-framework v0.6.0
 	sigs.k8s.io/kustomize/kyaml v0.19.0
 	sigs.k8s.io/yaml v1.4.0
@@ -137,10 +136,13 @@ require (
 	k8s.io/klog/v2 v2.130.1 // indirect
 	k8s.io/kube-openapi v0.0.0-20250318190949-c8a335a9a2ff // indirect
 	k8s.io/kubectl v0.33.2 // indirect
+	k8s.io/utils v0.0.0-20241104100929-3ea5e8cea738 // indirect
 	oras.land/oras-go/v2 v2.6.0 // indirect
 	sigs.k8s.io/controller-runtime v0.20.0 // indirect
 	sigs.k8s.io/json v0.0.0-20241010143419-9aa6b5e7a4b3 // indirect
 	sigs.k8s.io/kustomize/api v0.19.0 // indirect
 	sigs.k8s.io/randfill v1.0.0 // indirect
 	sigs.k8s.io/structured-merge-diff/v4 v4.6.0 // indirect
 )
+
+replace github.com/krateoplatformops/unstructured-runtime => /Users/matteogastaldello/Documents/unstructured-runtime

go.sum

@@ -179,8 +179,6 @@ github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
 github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
 github.com/krateoplatformops/plumbing v0.6.1 h1:UxQjxvJwj6ORso/RJePQv7PRC75tCcupCpYZz98BaRI=
 github.com/krateoplatformops/plumbing v0.6.1/go.mod h1:mQ/sm0viyKgfR2ARzHuwCpY0rcyMKqCv8a8SOu52yYQ=
-github.com/krateoplatformops/unstructured-runtime v0.2.1 h1:KQ//tYaSknQByKi1GuJf83ZNi+2jDell3E/6dK5o2H0=
-github.com/krateoplatformops/unstructured-runtime v0.2.1/go.mod h1:hY1WdGSugozFs5p/MTlQot3yM71Il6/B+UkZv43FL9E=
 github.com/kylelemons/godebug v1.1.0 h1:RPNrshWIDI6G2gRW9EHilWtl7Z6Sb1BR0xunSBf0SNc=
 github.com/kylelemons/godebug v1.1.0/go.mod h1:9/0rRGxNHcop5bhtWyNeEfOS8JIWk580+fNqagV/RAw=
 github.com/lann/builder v0.0.0-20180802200727-47ae307949d0 h1:SOEGU9fKiNWd/HOJuq6+3iTQz8KNCLtVX6idSoTLdUw=

internal/composition/composition.go

@@ -6,6 +6,7 @@ import (
 	"net/http"
 	"os"
 	"path/filepath"
+	"time"
 
 	compositionMeta "github.com/krateoplatformops/composition-dynamic-controller/internal/meta"
 
@@ -40,6 +41,8 @@ var (
 )
 
 const (
+	reasonReconciliationGracefullyPaused event.Reason = "ReconciliationGracefullyPaused"
+
 	// Event reasons
 	reasonCreated   = "CompositionCreated"
 	reasonDeleted   = "CompositionDeleted"
@@ -98,6 +101,24 @@ func (h *handler) Observe(ctx context.Context, mg *unstructured.Unstructured) (c
 		WithValues("namespace", mg.GetNamespace())
 
 	compositionMeta.SetReleaseName(mg, mg.GetName())
+	if _, p := compositionMeta.GetGracefullyPausedTime(mg); p && compositionMeta.IsGracefullyPaused(mg) {
+		log.Debug("Composition is gracefully paused, skipping observe.")
+		h.eventRecorder.Event(mg, event.Normal(reasonReconciliationGracefullyPaused, "Observe", "Reconciliation is paused via the gracefully paused annotation."))
+		return controller.ExternalObservation{
+			ResourceExists:   true,
+			ResourceUpToDate: true,
+		}, nil
+	}
+	// Immediately remove the gracefully paused time annotation if the composition is not gracefully paused.
+	meta.RemoveAnnotations(mg, compositionMeta.AnnotationKeyReconciliationGracefullyPausedTime)
+	mg, err := tools.Update(ctx, mg, tools.UpdateOptions{
+		Pluralizer:    h.pluralizer,
+		DynamicClient: h.dynamicClient,
+	})
+	if err != nil {
+		log.Debug("Updating composition", "error", err)
+		return controller.ExternalObservation{}, fmt.Errorf("updating composition: %w", err)
+	}
 
 	if h.packageInfoGetter == nil {
 		return controller.ExternalObservation{}, fmt.Errorf("helm chart package info getter must be specified")
@@ -220,21 +241,18 @@ func (h *handler) Observe(ctx context.Context, mg *unstructured.Unstructured) (c
 		}, nil
 	}
 
-	err = setAvaibleStatus(mg, pkg, "Composition up-to-date")
+	err = setAvaibleStatus(mg, pkg, "Composition up-to-date", false)
 	if err != nil {
 		log.Debug("Setting available status", "error", err)
 		return controller.ExternalObservation{}, err
 	}
-	mg, err = tools.UpdateStatus(ctx, mg, tools.UpdateOptions{
-		Pluralizer:    h.pluralizer,
-		DynamicClient: h.dynamicClient,
-	})
 	if err != nil {
 		log.Debug("Updating cr status with condition", "error", err, "condition", condition.Available())
 		return controller.ExternalObservation{}, err
 	}
 
 	log.Debug("Composition Observed - installed", "package", pkg.URL)
+
 	return controller.ExternalObservation{
 		ResourceExists:   true,
 		ResourceUpToDate: true,
@@ -248,6 +266,12 @@ func (h *handler) Create(ctx context.Context, mg *unstructured.Unstructured) err
 		WithValues("name", mg.GetName()).
 		WithValues("namespace", mg.GetNamespace())
 
+	if _, p := compositionMeta.GetGracefullyPausedTime(mg); p && compositionMeta.IsGracefullyPaused(mg) {
+		log.Debug("Composition is gracefully paused, skipping create.")
+		h.eventRecorder.Event(mg, event.Normal(reasonReconciliationGracefullyPaused, "Update", "Reconciliation is paused via the gracefully paused annotation."))
+		return nil
+	}
+
 	compositionMeta.SetReleaseName(mg, mg.GetName())
 	mg, err := tools.Update(ctx, mg, tools.UpdateOptions{
 		Pluralizer:    h.pluralizer,
@@ -343,12 +367,14 @@ func (h *handler) Create(ctx context.Context, mg *unstructured.Unstructured) err
 	h.logger.Debug("Composition created.", "package", pkg.URL)
 
 	h.eventRecorder.Event(mg, event.Normal(reasonCreated, "Create", fmt.Sprintf("Composition created: %s", mg.GetName())))
-	err = setAvaibleStatus(mg, pkg, "Composition created")
+	err = setAvaibleStatus(mg, pkg, "Composition created", true)
 	if err != nil {
 		log.Debug("Setting available status", "error", err)
 		return err
 	}
-	_, err = tools.UpdateStatus(ctx, mg, tools.UpdateOptions{
+
+	meta.RemoveAnnotations(mg, compositionMeta.AnnotationKeyReconciliationGracefullyPausedTime)
+	_, err = tools.Update(ctx, mg, tools.UpdateOptions{
 		Pluralizer:    h.pluralizer,
 		DynamicClient: h.dynamicClient,
 	})
@@ -362,6 +388,12 @@ func (h *handler) Update(ctx context.Context, mg *unstructured.Unstructured) err
 		WithValues("name", mg.GetName()).
 		WithValues("namespace", mg.GetNamespace())
 
+	if _, p := compositionMeta.GetGracefullyPausedTime(mg); p && compositionMeta.IsGracefullyPaused(mg) {
+		log.Debug("Composition is gracefully paused, skipping update.")
+		h.eventRecorder.Event(mg, event.Normal(reasonReconciliationGracefullyPaused, "Update", "Reconciliation is paused via the gracefully paused annotation."))
+		return nil
+	}
+
 	log.Debug("Handling composition values update.")
 
 	if h.packageInfoGetter == nil {
@@ -402,16 +434,36 @@ func (h *handler) Update(ctx context.Context, mg *unstructured.Unstructured) err
 	log.Debug("Composition values updated.", "package", pkg.URL)
 
 	h.eventRecorder.Event(mg, event.Normal(reasonUpdated, "Update", fmt.Sprintf("Updated composition: %s", mg.GetName())))
-	err = setAvaibleStatus(mg, pkg, "Composition values updated.")
-	if err != nil {
-		log.Debug("Setting available status", "error", err)
-		return err
+
+	if compositionMeta.IsGracefullyPaused(mg) {
+		err = setGracefullyPausedCondition(mg, pkg)
+		if err != nil {
+			log.Debug("Setting gracefully paused condition", "error", err)
+			return err
+		}
+		compositionMeta.SetGracefullyPausedTime(mg, time.Now())
+		log.Debug("Composition is gracefully paused.")
+		h.eventRecorder.Event(mg, event.Normal(reasonReconciliationGracefullyPaused, "Update", "Reconciliation is paused via the gracefully paused annotation."))
+	} else {
+		// Normal behavior, set available status
+		err = setAvaibleStatus(mg, pkg, "Composition values updated.", true)
+		if err != nil {
+			log.Debug("Setting available status", "error", err)
+			return err
+		}
+
+		meta.RemoveAnnotations(mg, compositionMeta.AnnotationKeyReconciliationGracefullyPausedTime)
 	}
-	_, err = tools.UpdateStatus(ctx, mg, tools.UpdateOptions{
+
+	_, err = tools.Update(ctx, mg, tools.UpdateOptions{
 		Pluralizer:    h.pluralizer,
 		DynamicClient: h.dynamicClient,
 	})
-	return err
+	if err != nil {
+		log.Debug("Updating cr with values", "error", err)
+		return err
+	}
+	return nil
 }
 
 func (h *handler) Delete(ctx context.Context, mg *unstructured.Unstructured) error {
@@ -421,6 +473,12 @@ func (h *handler) Delete(ctx context.Context, mg *unstructured.Unstructured) err
 		WithValues("name", mg.GetName()).
 		WithValues("namespace", mg.GetNamespace())
 
+	if _, p := compositionMeta.GetGracefullyPausedTime(mg); p && compositionMeta.IsGracefullyPaused(mg) {
+		log.Debug("Composition is gracefully paused, skipping delete.")
+		h.eventRecorder.Event(mg, event.Normal(reasonReconciliationGracefullyPaused, "Delete", "Reconciliation is paused via the gracefully paused annotation."))
+		return nil
+	}
+
 	if h.packageInfoGetter == nil {
 		return fmt.Errorf("helm chart package info getter must be specified")
 	}
@@ -497,6 +555,16 @@ func (h *handler) Delete(ctx context.Context, mg *unstructured.Unstructured) err
 
 	h.eventRecorder.Event(mg, event.Normal(reasonDeleted, "Delete", fmt.Sprintf("Deleted composition: %s", mg.GetName())))
 	log.Debug("Composition package removed.", "package", pkg.URL)
+	meta.RemoveAnnotations(mg, compositionMeta.AnnotationKeyReconciliationGracefullyPausedTime)
+
+	_, err = tools.Update(ctx, mg, tools.UpdateOptions{
+		Pluralizer:    h.pluralizer,
+		DynamicClient: h.dynamicClient,
+	})
+	if err != nil {
+		log.Debug("Updating cr with values", "error", err)
+		return fmt.Errorf("updating cr with values: %w", err)
+	}
 
 	return nil
 }

internal/composition/support.go

@@ -3,6 +3,8 @@ package composition
 import (
 	"fmt"
 
+	compositionCondition "github.com/krateoplatformops/composition-dynamic-controller/internal/condition"
+
 	"github.com/krateoplatformops/composition-dynamic-controller/internal/tools/helmchart/archive"
 	"github.com/krateoplatformops/unstructured-runtime/pkg/controller/objectref"
 	"github.com/krateoplatformops/unstructured-runtime/pkg/pluralizer"
@@ -19,19 +21,22 @@ type ManagedResource struct {
 	Namespace  string `json:"namespace"`
 }
 
-func setAvaibleStatus(mg *unstructured.Unstructured, pkg *archive.Info, message string) error {
+func setAvaibleStatus(mg *unstructured.Unstructured, pkg *archive.Info, message string, force bool) error {
 	if pkg == nil {
 		return fmt.Errorf("package info is nil")
 	}
 
 	unstructured.SetNestedField(mg.Object, pkg.Version, "status", "helmChartVersion")
 	unstructured.SetNestedField(mg.Object, pkg.URL, "status", "helmChartUrl")
 
-	currentCondition := unstructuredtools.GetCondition(mg, condition.Available().Type, condition.Available().Reason)
+	if !force {
+		currentCondition := unstructuredtools.GetCondition(mg, condition.Available().Type, condition.Available().Reason)
 
-	if currentCondition != nil && currentCondition.Message == message {
-		return nil
+		if currentCondition != nil && currentCondition.Message == message {
+			return nil
+		}
 	}
+
 	cond := condition.Available()
 	cond.Message = message
 	err := unstructuredtools.SetConditions(mg, cond)
@@ -41,6 +46,25 @@ func setAvaibleStatus(mg *unstructured.Unstructured, pkg *archive.Info, message
 	return nil
 }
 
+func setGracefullyPausedCondition(mg *unstructured.Unstructured, pkg *archive.Info) error {
+	if pkg == nil {
+		return fmt.Errorf("package info is nil")
+	}
+
+	currentCondition := unstructuredtools.GetCondition(mg, compositionCondition.ReconcileGracefullyPaused().Type, compositionCondition.ReconcileGracefullyPaused().Reason)
+
+	if currentCondition != nil && currentCondition.Message == "Composition is gracefully paused." {
+		return nil
+	}
+	cond := compositionCondition.ReconcileGracefullyPaused()
+	cond.Message = "Composition is gracefully paused."
+	err := unstructuredtools.SetConditions(mg, cond)
+	if err != nil {
+		return fmt.Errorf("setting condition: %w", err)
+	}
+	return nil
+}
+
 func setManagedResources(mg *unstructured.Unstructured, managed []interface{}) {
 	status := mg.Object["status"]
 	if status == nil {

internal/condition/condition.go

@@ -0,0 +1,21 @@
+package condition
+
+import (
+	"github.com/krateoplatformops/unstructured-runtime/pkg/tools/unstructured/condition"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+)
+
+const (
+	ReasonReconcileGracefullyPaused = "ReconcileGracefullyPaused"
+)
+
+// ReconcilePaused returns a condition that indicates reconciliation on
+// the managed resource is paused via the pause annotation.
+func ReconcileGracefullyPaused() metav1.Condition {
+	return metav1.Condition{
+		Type:               condition.TypeReady,
+		Status:             metav1.ConditionTrue,
+		LastTransitionTime: metav1.Now(),
+		Reason:             ReasonReconcileGracefullyPaused,
+	}
+}

internal/condition/condition_test.go

@@ -0,0 +1,44 @@
+package condition
+
+import (
+	"testing"
+
+	"github.com/krateoplatformops/unstructured-runtime/pkg/tools/unstructured/condition"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+)
+
+func TestReconcileGracefullyPaused(t *testing.T) {
+	result := ReconcileGracefullyPaused()
+
+	// Test Type
+	if result.Type != condition.TypeSynced {
+		t.Errorf("Expected Type to be %s, got %s", condition.TypeSynced, result.Type)
+	}
+
+	// Test Status
+	if result.Status != metav1.ConditionFalse {
+		t.Errorf("Expected Status to be %s, got %s", metav1.ConditionFalse, result.Status)
+	}
+
+	// Test Reason
+	if result.Reason != ReasonReconcileGracefullyPaused {
+		t.Errorf("Expected Reason to be %s, got %s", ReasonReconcileGracefullyPaused, result.Reason)
+	}
+
+	// Test LastTransitionTime is set (not zero)
+	if result.LastTransitionTime.IsZero() {
+		t.Error("Expected LastTransitionTime to be set, got zero time")
+	}
+
+	// Test Message is empty (default)
+	if result.Message != "" {
+		t.Errorf("Expected Message to be empty, got %s", result.Message)
+	}
+}
+
+func TestReasonReconcileGracefullyPausedConstant(t *testing.T) {
+	expected := "ReconcileGracefullyPaused"
+	if ReasonReconcileGracefullyPaused != expected {
+		t.Errorf("Expected constant to be %s, got %s", expected, ReasonReconcileGracefullyPaused)
+	}
+}

internal/meta/meta.go

@@ -1,6 +1,9 @@
 package meta
 
 import (
+	"time"
+
+	"github.com/krateoplatformops/unstructured-runtime/pkg/meta"
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 	"k8s.io/apimachinery/pkg/runtime/schema"
 )
@@ -15,6 +18,15 @@ const (
 
 	// ReleaseNameLabel is the label used to identify the release name of a Helm chart that can be different from the name of the resource.
 	ReleaseNameLabel = "krateo.io/release-name"
+
+	// AnnotationKeyReconciliationGracefullyPaused is the key in the annotations map
+	// that indicates whether the reconciliation of the resource is gracefully paused.
+	AnnotationKeyReconciliationGracefullyPaused = "krateo.io/gracefully-paused"
+
+	// AnnotationKeyReconciliationGracefullyPausedTime is the key in the annotations map
+	// that indicates the time when the reconciliation was gracefully paused.
+	// This is used to track how long the resource has been paused.
+	AnnotationKeyReconciliationGracefullyPausedTime = "krateo.io/gracefully-paused-time"
 )
 
 func GetReleaseName(o metav1.Object) string {
@@ -58,3 +70,25 @@ func SetCompositionDefinitionLabels(o metav1.Object, cdInfo CompositionDefinitio
 
 	o.SetLabels(labels)
 }
+
+// IsGracefullyPaused returns true if the object has the AnnotationKeyGracefullyPaused
+// annotation set to `true`.
+func IsGracefullyPaused(o metav1.Object) bool {
+	return o.GetAnnotations()[AnnotationKeyReconciliationGracefullyPaused] == "true"
+}
+
+func SetGracefullyPausedTime(o metav1.Object, t time.Time) {
+	meta.AddAnnotations(o, map[string]string{AnnotationKeyReconciliationGracefullyPausedTime: t.Format(time.RFC3339)})
+}
+
+func GetGracefullyPausedTime(o metav1.Object) (time.Time, bool) {
+	t, ok := o.GetAnnotations()[AnnotationKeyReconciliationGracefullyPausedTime]
+	if !ok {
+		return time.Time{}, false
+	}
+	pausedTime, err := time.Parse(time.RFC3339, t)
+	if err != nil {
+		return time.Time{}, false
+	}
+	return pausedTime, true
+}