feat: annotate argocd context to stage and move deep link back to stage details (#3603)

Signed-off-by: Mayursinh Sarvaiya <[email protected]>
Signed-off-by: Hidde Beydals <[email protected]>
Co-authored-by: Hidde Beydals <[email protected]>
Co-authored-by: Kent Rancourt <[email protected]>

Author: 3 people

api/v1alpha1/annotations.go

@@ -38,4 +38,8 @@ const (
 	// AnnotationKeyPromotion is an annotation key that can be set on a
 	// resource to indicate that it is related to a specific promotion.
 	AnnotationKeyPromotion = "kargo.akuity.io/promotion"
+
+	// AnnotationKeyArgoCDContext is an annotation key that is set on a Stage
+	// to reference the last ArgoCD Applications that were part of a Promotion.
+	AnnotationKeyArgoCDContext = "kargo.akuity.io/argocd-context"
 )

internal/api/finalizers.go

@@ -84,6 +84,12 @@ func patchAnnotation(ctx context.Context, c client.Client, obj client.Object, ke
 	})
 }
 
+func deleteAnnotation(ctx context.Context, c client.Client, obj client.Object, key string) error {
+	return patchAnnotations(ctx, c, obj, map[string]*string{
+		key: nil,
+	})
+}
+
 func patchAnnotations(
 	ctx context.Context,
 	c client.Client,

internal/api/finalizers_test.go

@@ -224,3 +224,80 @@ func Test_patchAnnotation(t *testing.T) {
 		})
 	}
 }
+
+func Test_deleteAnnotation(t *testing.T) {
+	scheme := k8sruntime.NewScheme()
+	require.NoError(t, kargoapi.SchemeBuilder.AddToScheme(scheme))
+
+	newFakeClient := func(obj ...client.Object) client.Client {
+		return fake.NewClientBuilder().
+			WithScheme(scheme).
+			WithObjects(obj...).
+			Build()
+	}
+
+	testCases := map[string]struct {
+		obj         client.Object
+		client      client.Client
+		key         string
+		value       string
+		errExpected bool
+	}{
+		"stage without annotation": {
+			obj: &kargoapi.Stage{
+				ObjectMeta: metav1.ObjectMeta{
+					Namespace: "test",
+					Name:      "stage",
+				},
+			},
+			client: newFakeClient(&kargoapi.Stage{
+				ObjectMeta: metav1.ObjectMeta{
+					Namespace: "test",
+					Name:      "stage",
+				},
+			}),
+			key: "key",
+		},
+		"stage with existing annotation": {
+			obj: &kargoapi.Stage{
+				ObjectMeta: metav1.ObjectMeta{
+					Namespace: "test",
+					Name:      "stage",
+				},
+			},
+			client: newFakeClient(&kargoapi.Stage{
+				ObjectMeta: metav1.ObjectMeta{
+					Namespace: "test",
+					Name:      "stage",
+					Annotations: map[string]string{
+						"key": "value",
+					},
+				},
+			}),
+			key: "key",
+		},
+		"non-existing stage": {
+			obj: &kargoapi.Stage{
+				ObjectMeta: metav1.ObjectMeta{
+					Namespace: "test",
+					Name:      "stage",
+				},
+			},
+			client:      newFakeClient(),
+			key:         "key",
+			value:       "value",
+			errExpected: true,
+		},
+	}
+	for name, tc := range testCases {
+		t.Run(name, func(t *testing.T) {
+			t.Parallel()
+			err := deleteAnnotation(context.Background(), tc.client, tc.obj, tc.key)
+			if tc.errExpected {
+				require.Error(t, err)
+				return
+			}
+			require.NotContains(t, tc.obj.GetAnnotations(), tc.key)
+		})
+	}
+}

internal/api/stage.go

@@ -2,6 +2,7 @@ package api
 
 import (
 	"context"
+	"encoding/json"
 	"errors"
 	"fmt"
 	"slices"
@@ -126,6 +127,54 @@ func RefreshStage(
 	return stage, nil
 }
 
+// AnnotateStageWithArgoCDContext annotates a Stage with the ArgoCD context
+// necessary for the frontend to display ArgoCD information for the Stage.
+//
+// The annotation value is a JSON-encoded list of ArgoCD apps that are
+// associated with the Stage, constructed from the HealthCheckSteps from
+// the latest Promotion.
+//
+// If no ArgoCD apps are found, the annotation is removed.
+func AnnotateStageWithArgoCDContext(
+	ctx context.Context,
+	c client.Client,
+	healthChecks []kargoapi.HealthCheckStep,
+	stage *kargoapi.Stage,
+) error {
+	var argoCDApps []map[string]any
+	for _, healthCheck := range healthChecks {
+		healthCheckConfig := healthCheck.GetConfig()
+
+		appsList, ok := healthCheckConfig["apps"].([]any)
+		if !ok {
+			continue
+		}
+
+		for _, rawApp := range appsList {
+			appConfig, ok := rawApp.(map[string]any)
+			if !ok {
+				continue
+			}
+			argoCDApps = append(argoCDApps, map[string]any{
+				"name":      appConfig["name"],
+				"namespace": appConfig["namespace"],
+			})
+		}
+	}
+
+	// If we did not find any ArgoCD apps, we should remove the annotation.
+	if len(argoCDApps) == 0 {
+		return deleteAnnotation(ctx, c, stage, kargoapi.AnnotationKeyArgoCDContext)
+	}
+
+	// Marshal the ArgoCD context to JSON and set the annotation on the Stage.
+	argoCDAppsJSON, err := json.Marshal(argoCDApps)
+	if err != nil {
+		return fmt.Errorf("failed to marshal ArgoCD context: %w", err)
+	}
+	return patchAnnotation(ctx, c, stage, kargoapi.AnnotationKeyArgoCDContext, string(argoCDAppsJSON))
+}
+
 // ReverifyStageFreight forces reconfirmation of the verification of the
 // Freight associated with a Stage by setting an AnnotationKeyReverify
 // annotation on the Stage, causing the controller to rerun the verification.

internal/api/stage_test.go

@@ -7,6 +7,7 @@ import (
 	"time"
 
 	"github.com/stretchr/testify/require"
+	apiextensionsv1 "k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1"
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 	k8sruntime "k8s.io/apimachinery/pkg/runtime"
 	"k8s.io/apimachinery/pkg/types"
@@ -551,3 +552,85 @@ func TestAbortStageFreightVerification(t *testing.T) {
 		}).String(), stage.Annotations[kargoapi.AnnotationKeyAbort])
 	})
 }
+
+func TestAnnotateStageWithArgoCDContext(t *testing.T) {
+	scheme := k8sruntime.NewScheme()
+	require.NoError(t, kargoapi.SchemeBuilder.AddToScheme(scheme))
+
+	t.Run("not found", func(t *testing.T) {
+		c := fake.NewClientBuilder().WithScheme(scheme).Build()
+
+		err := AnnotateStageWithArgoCDContext(context.TODO(), c, []kargoapi.HealthCheckStep{}, &kargoapi.Stage{
+			ObjectMeta: metav1.ObjectMeta{
+				Name:      "fake-stage",
+				Namespace: "fake-namespace",
+			},
+		})
+		require.ErrorContains(t, err, "not found")
+	})
+
+	t.Run("success", func(t *testing.T) {
+		c := fake.NewClientBuilder().WithScheme(scheme).WithObjects(
+			&kargoapi.Stage{
+				ObjectMeta: metav1.ObjectMeta{
+					Name:      "fake-stage",
+					Namespace: "fake-namespace",
+				},
+			},
+		).Build()
+
+		err := AnnotateStageWithArgoCDContext(context.TODO(), c, []kargoapi.HealthCheckStep{
+			{
+				Uses: "argocd-update",
+				Config: &apiextensionsv1.JSON{
+					Raw: []byte(`{"apps": [{"name": "fake-argo-app", "namespace": "fake-argo-namespace"}]}`),
+				},
+			},
+		}, &kargoapi.Stage{
+			ObjectMeta: metav1.ObjectMeta{
+				Name:      "fake-stage",
+				Namespace: "fake-namespace",
+			},
+		})
+		require.NoError(t, err)
+
+		stage, err := GetStage(context.TODO(), c, types.NamespacedName{
+			Namespace: "fake-namespace",
+			Name:      "fake-stage",
+		})
+		require.NoError(t, err)
+		require.Equal(t,
+			`[{"name":"fake-argo-app","namespace":"fake-argo-namespace"}]`,
+			stage.Annotations[kargoapi.AnnotationKeyArgoCDContext])
+	})
+
+	t.Run("no ArgoCD apps", func(t *testing.T) {
+		c := fake.NewClientBuilder().WithScheme(scheme).WithObjects(
+			&kargoapi.Stage{
+				ObjectMeta: metav1.ObjectMeta{
+					Name:      "fake-stage",
+					Namespace: "fake-namespace",
+					Annotations: map[string]string{
+						kargoapi.AnnotationKeyArgoCDContext: "fake-annotation",
+					},
+				},
+			},
+		).Build()
+
+		err := AnnotateStageWithArgoCDContext(context.TODO(), c, []kargoapi.HealthCheckStep{}, &kargoapi.Stage{
+			ObjectMeta: metav1.ObjectMeta{
+				Name:      "fake-stage",
+				Namespace: "fake-namespace",
+			},
+		})
+		require.NoError(t, err)
+
+		stage, err := GetStage(context.TODO(), c, types.NamespacedName{
+			Namespace: "fake-namespace",
+			Name:      "fake-stage",
+		})
+		require.NoError(t, err)
+
+		require.NotContains(t, stage.Annotations, kargoapi.AnnotationKeyArgoCDContext)
+	})
+}

internal/controller/stages/control_flow_stages.go

@@ -215,6 +215,14 @@ func (r *ControlFlowStageReconciler) Reconcile(ctx context.Context, req ctrl.Req
 		return ctrl.Result{Requeue: ok}, err
 	}
 
+	// Remove any stale annotations from the Stage which are not relevant to
+	// a control flow Stage.
+	if stage.GetAnnotations()[kargoapi.AnnotationKeyArgoCDContext] != "" {
+		if err := api.AnnotateStageWithArgoCDContext(ctx, r.client, nil, stage); err != nil {
+			logger.Error(err, "failed to remove Argo CD context annotation from Stage")
+		}
+	}
+
 	// Reconcile the Stage.
 	logger.Debug("reconciling Stage")
 	newStatus, reconcileErr := r.reconcile(ctx, stage, time.Now())

internal/controller/stages/control_flow_stages_test.go

@@ -147,6 +147,30 @@ func TestControlFlowStageReconciler_Reconcile(t *testing.T) {
 				assert.Contains(t, stage.Finalizers, kargoapi.FinalizerName)
 			},
 		},
+		{
+			name: "removes stale annotations",
+			req:  ctrl.Request{NamespacedName: testStage},
+			stage: &kargoapi.Stage{
+				ObjectMeta: metav1.ObjectMeta{
+					Namespace:  testProject,
+					Name:       testStageName,
+					Finalizers: []string{kargoapi.FinalizerName},
+					Annotations: map[string]string{
+						kargoapi.AnnotationKeyArgoCDContext: "old-argocd-context",
+					},
+				},
+			},
+			assertions: func(t *testing.T, c client.Client, result ctrl.Result, err error) {
+				require.NoError(t, err)
+				assert.Equal(t, ctrl.Result{}, result)
+
+				// Verify annotation was removed
+				stage := &kargoapi.Stage{}
+				err = c.Get(context.Background(), testStage, stage)
+				require.NoError(t, err)
+				assert.NotContains(t, stage.Annotations, kargoapi.AnnotationKeyArgoCDContext)
+			},
+		},
 		{
 			name: "reconcile error",
 			req:  ctrl.Request{NamespacedName: testStage},

internal/controller/stages/regular_stages.go

@@ -636,6 +636,18 @@ func (r *RegularStageReconciler) syncPromotions(
 					Message:            "Waiting for verification to be performed after successful promotion",
 					ObservedGeneration: stage.Generation,
 				})
+
+				// Annotate the Stage with the latest information related to
+				// ArgoCD Applications. This is used to provide deep links to the
+				// ArgoCD UI for the Stage in the Kargo UI.
+				//
+				// NB: If the health checks do not include ArgoCD Applications,
+				// then the annotation will be removed.
+				if err := api.AnnotateStageWithArgoCDContext(ctx, r.client, p.Status.HealthChecks, stage); err != nil {
+					// Let the error be logged, but do not return it as it is not
+					// critical to the operation of the Stage.
+					logger.Error(err, "failed to annotate Stage with ArgoCD context")
+				}
 			}
 		}