Introduce reconcile.fluxcd.io/forceAt annotation

Signed-off-by: Matheus Pimenta <[email protected]>

Author: matheuscscp

apis/meta/annotations.go

@@ -18,13 +18,22 @@ package meta
 
 const (
 	// ReconcileRequestAnnotation is the annotation used for triggering a reconciliation
-	// outside of a defined schedule. The value is interpreted as a token, and any change
+	// outside of a defined interval. The value is interpreted as a token, and any change
 	// in value SHOULD trigger a reconciliation.
 	ReconcileRequestAnnotation string = "reconcile.fluxcd.io/requestedAt"
+
+	// ForceRequestAnnotation is the annotation used for triggering a one-off forced
+	// reconciliation, for example, of a HelmRelease when there are no new changes,
+	// or of something that runs on a schedule when the schedule is not due at the moment.
+	// The specific conditions for triggering a forced reconciliation depend on the
+	// specific controller implementation, but the annotation is used to standardize
+	// the mechanism across controllers. The value is interpreted as a token, and must
+	// equal the value of ReconcileRequestAnnotation in order to trigger a release.
+	ForceRequestAnnotation string = "reconcile.fluxcd.io/forceAt"
 )
 
 // ReconcileAnnotationValue returns a value for the reconciliation request annotation, which can be used to detect
-// changes; and, a boolean indicating whether the annotation was set.
+// changes, and a boolean indicating whether the annotation was set.
 func ReconcileAnnotationValue(annotations map[string]string) (string, bool) {
 	requestedAt, ok := annotations[ReconcileRequestAnnotation]
 	return requestedAt, ok
@@ -67,3 +76,68 @@ type StatusWithHandledReconcileRequest interface {
 type StatusWithHandledReconcileRequestSetter interface {
 	SetLastHandledReconcileRequest(token string)
 }
+
+// ForceRequestStatus is a struct to embed in a status type, so that all types using the mechanism have the same
+// field. Use it like this:
+//
+//		type FooStatus struct {
+//	 	meta.ForceRequestStatus `json:",inline"`
+//	 	// other status fields...
+//		}
+type ForceRequestStatus struct {
+	// LastHandledForceAt holds the value of the most recent
+	// force request value, so a change of the annotation value
+	// can be detected.
+	// +optional
+	LastHandledForceAt string `json:"lastHandledForceAt,omitempty"`
+}
+
+// ShouldHandleForceRequest returns true if the object has a force request
+// annotation, and the value of the annotation matches the value of the
+// ReconcileRequestAnnotation annotation.
+//
+// To ensure that the force request is handled only once, the value of
+// <ObjectType>Status.LastHandledForceAt is updated to match the value of the
+// force request annotation (even if the force request is not handled because
+// the value of the ReconcileRequestAnnotation annotation does not match).
+func ShouldHandleForceRequest(obj interface {
+	ObjectWithAnnotationRequests
+	GetLastHandledForceRequestStatus() *string
+}) bool {
+	return HandleAnnotationRequest(obj, ForceRequestAnnotation, obj.GetLastHandledForceRequestStatus())
+}
+
+// ObjectWithAnnotationRequests is an interface that describes an object
+// that has annotations and a status with a last handled reconcile request.
+// +k8s:deepcopy-gen=false
+type ObjectWithAnnotationRequests interface {
+	GetAnnotations() map[string]string
+	StatusWithHandledReconcileRequest
+}
+
+// HandleAnnotationRequest returns true if the object has a request annotation, and
+// the value of the annotation matches the value of the ReconcileRequestAnnotation
+// annotation.
+//
+// The lastHandled argument is used to ensure that the request is handled only
+// once, and is updated to match the value of the request annotation (even if
+// the request is not handled because the value of the ReconcileRequestAnnotation
+// annotation does not match).
+func HandleAnnotationRequest(obj ObjectWithAnnotationRequests, annotation string, lastHandled *string) bool {
+	requestAt, requestOk := obj.GetAnnotations()[annotation]
+	reconcileAt, reconcileOk := ReconcileAnnotationValue(obj.GetAnnotations())
+
+	var lastHandledRequest string
+	if requestOk {
+		lastHandledRequest = *lastHandled
+		*lastHandled = requestAt
+	}
+
+	if requestOk && reconcileOk && requestAt == reconcileAt {
+		lastHandledReconcile := obj.GetLastHandledReconcileRequest()
+		if lastHandledReconcile != reconcileAt && lastHandledRequest != requestAt {
+			return true
+		}
+	}
+	return false
+}

apis/meta/annotations_test.go

@@ -23,14 +23,27 @@ import (
 
 type whateverStatus struct {
 	ReconcileRequestStatus `json:",inline"`
+	ForceRequestStatus     `json:",inline"`
 }
 
 type whatever struct {
 	Annotations map[string]string
-	Status      whateverStatus `json:"status,omitempty"`
+	Status      whateverStatus `json:"status"`
 }
 
-func TestGetAnnotationValue(t *testing.T) {
+func (w *whatever) GetAnnotations() map[string]string {
+	return w.Annotations
+}
+
+func (w *whatever) GetLastHandledReconcileRequest() string {
+	return w.Status.GetLastHandledReconcileRequest()
+}
+
+func (w *whatever) GetLastHandledForceRequestStatus() *string {
+	return &w.Status.LastHandledForceAt
+}
+
+func TestGetReconcileAnnotationValue(t *testing.T) {
 	obj := whatever{
 		Annotations: map[string]string{},
 	}
@@ -65,3 +78,112 @@ func TestGetAnnotationValue(t *testing.T) {
 		t.Error("expected to detect change in annotation value")
 	}
 }
+
+func TestShouldHandleForceRequest(t *testing.T) {
+	obj := &whatever{
+		Annotations: map[string]string{
+			ReconcileRequestAnnotation: "b",
+			ForceRequestAnnotation:     "b",
+		},
+		Status: whateverStatus{
+			ReconcileRequestStatus: ReconcileRequestStatus{
+				LastHandledReconcileAt: "a",
+			},
+			ForceRequestStatus: ForceRequestStatus{
+				LastHandledForceAt: "a",
+			},
+		},
+	}
+
+	if !ShouldHandleForceRequest(obj) {
+		t.Error("ShouldHandleForceRequest() = false")
+	}
+
+	if obj.Status.LastHandledForceAt != "b" {
+		t.Error("ShouldHandleForceRequest did not update LastHandledForceAt")
+	}
+}
+
+func TestHandleAnnotationRequest(t *testing.T) {
+	const requestAnnotation = "requestAnnotation"
+
+	tests := []struct {
+		name                     string
+		annotations              map[string]string
+		lastHandledReconcile     string
+		lastHandledRequest       string
+		want                     bool
+		expectLastHandledRequest string
+	}{
+		{
+			name: "valid request and reconcile annotations",
+			annotations: map[string]string{
+				ReconcileRequestAnnotation: "b",
+				requestAnnotation:          "b",
+			},
+			want:                     true,
+			expectLastHandledRequest: "b",
+		},
+		{
+			name: "mismatched annotations",
+			annotations: map[string]string{
+				ReconcileRequestAnnotation: "b",
+				requestAnnotation:          "c",
+			},
+			want:                     false,
+			expectLastHandledRequest: "c",
+		},
+		{
+			name: "reconcile matches previous request",
+			annotations: map[string]string{
+				ReconcileRequestAnnotation: "b",
+				requestAnnotation:          "b",
+			},
+			lastHandledReconcile:     "a",
+			lastHandledRequest:       "b",
+			want:                     false,
+			expectLastHandledRequest: "b",
+		},
+		{
+			name: "request matches previous reconcile",
+			annotations: map[string]string{
+				ReconcileRequestAnnotation: "b",
+				requestAnnotation:          "b",
+			},
+			lastHandledReconcile:     "b",
+			lastHandledRequest:       "a",
+			want:                     false,
+			expectLastHandledRequest: "b",
+		},
+		{
+			name:                     "missing annotations",
+			annotations:              map[string]string{},
+			lastHandledRequest:       "a",
+			want:                     false,
+			expectLastHandledRequest: "a",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			obj := &whatever{
+				Annotations: tt.annotations,
+				Status: whateverStatus{
+					ReconcileRequestStatus: ReconcileRequestStatus{
+						LastHandledReconcileAt: tt.lastHandledReconcile,
+					},
+				},
+			}
+
+			lastHandled := tt.lastHandledRequest
+			result := HandleAnnotationRequest(obj, requestAnnotation, &lastHandled)
+
+			if result != tt.want {
+				t.Errorf("HandleAnnotationRequest() = %v, want %v", result, tt.want)
+			}
+			if lastHandled != tt.expectLastHandledRequest {
+				t.Errorf("lastHandledRequest = %v, want %v", lastHandled, tt.expectLastHandledRequest)
+			}
+		})
+	}
+}