refactor: make engine and directive interfaces and related types supp…

…ort the notion of healthchecks (#2554)

Signed-off-by: Kent Rancourt <kent.rancourt@gmail.com>

api/v1alpha1/stage_types.go

@@ -6,6 +6,7 @@ import (
 	"slices"
 	"strings"
 
+	apiextensionsv1 "k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1"
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 )
 
@@ -77,17 +78,19 @@ const (
 type HealthState string
 
 const (
-	HealthStateHealthy     HealthState = "Healthy"
-	HealthStateUnhealthy   HealthState = "Unhealthy"
-	HealthStateProgressing HealthState = "Progressing"
-	HealthStateUnknown     HealthState = "Unknown"
+	HealthStateHealthy       HealthState = "Healthy"
+	HealthStateNotApplicable HealthState = "NotApplicable"
+	HealthStateProgressing   HealthState = "Progressing"
+	HealthStateUnknown       HealthState = "Unknown"
+	HealthStateUnhealthy     HealthState = "Unhealthy"
 )
 
 var stateOrder = map[HealthState]int{
-	HealthStateHealthy:     0,
-	HealthStateProgressing: 1,
-	HealthStateUnknown:     2,
-	HealthStateUnhealthy:   3,
+	HealthStateHealthy:       0,
+	HealthStateNotApplicable: 1,
+	HealthStateProgressing:   2,
+	HealthStateUnknown:       3,
+	HealthStateUnhealthy:     4,
 }
 
 // Merge returns the more severe of two HealthStates.
@@ -953,6 +956,11 @@ type Health struct {
 	Issues []string `json:"issues,omitempty" protobuf:"bytes,2,rep,name=issues"`
 	// ArgoCDApps describes the current state of any related ArgoCD Applications.
 	ArgoCDApps []ArgoCDAppStatus `json:"argoCDApps,omitempty" protobuf:"bytes,3,rep,name=argoCDApps"`
+	// Config is the opaque configuration of all health checks performed on this
+	// Stage.
+	Config *apiextensionsv1.JSON `json:"config,omitempty" protobuf:"bytes,4,opt,name=config"`
+	// Output is the opaque output of all health checks performed on this Stage.
+	Output *apiextensionsv1.JSON `json:"output,omitempty" protobuf:"bytes,5,opt,name=output"`
 }
 
 // ArgoCDAppStatus describes the current state of a single ArgoCD Application.

charts/kargo/resources/crds/kargo.akuity.io_stages.yaml

@@ -1864,13 +1864,22 @@ spec:
                       - namespace
                       type: object
                     type: array
+                  config:
+                    description: |-
+                      Config is the opaque configuration of all health checks performed on this
+                      Stage.
+                    x-kubernetes-preserve-unknown-fields: true
                   issues:
                     description: |-
                       Issues clarifies why a Stage in any state other than Healthy is in that
                       state. This field will always be the empty when a Stage is Healthy.
                     items:
                       type: string
                     type: array
+                  output:
+                    description: Output is the opaque output of all health checks
+                      performed on this Stage.
+                    x-kubernetes-preserve-unknown-fields: true
                   status:
                     description: Status describes the health of the Stage.
                     type: string

internal/controller/promotions/promotions.go

@@ -191,7 +191,6 @@ func newReconciler(
 	r := &reconciler{
 		kargoClient: kargoClient,
 		directivesEngine: directives.NewSimpleEngine(
-			directives.BuiltinsRegistry(),
 			credentialsDB,
 			kargoClient,
 			argocdClient,
@@ -515,12 +514,12 @@ func (r *reconciler) promote(
 		}
 	} else {
 		// If the Promotion has steps, execute them in sequence.
-		var steps []directives.Step
+		var steps []directives.PromotionStep
 		for _, step := range workingPromo.Spec.Steps {
-			steps = append(steps, directives.Step{
-				Directive: step.Step,
-				Alias:     step.As,
-				Config:    step.GetConfig(),
+			steps = append(steps, directives.PromotionStep{
+				Kind:   step.Step,
+				Alias:  step.As,
+				Config: step.GetConfig(),
 			})
 		}
 
@@ -536,19 +535,19 @@ func (r *reconciler) promote(
 			}
 		}()
 
-		status, err := r.directivesEngine.Execute(ctx, directives.PromotionContext{
+		res, err := r.directivesEngine.Promote(ctx, directives.PromotionContext{
 			WorkDir:         workDir,
 			Project:         stageNamespace,
 			Stage:           stageName,
 			FreightRequests: stage.Spec.RequestedFreight,
 			Freight:         *workingPromo.Status.FreightCollection.DeepCopy(),
 		}, steps)
-		switch status {
-		case directives.StatusPending:
+		switch res.Status {
+		case directives.PromotionStatusPending:
 			workingPromo.Status.Phase = kargoapi.PromotionPhaseRunning
-		case directives.StatusSuccess:
+		case directives.PromotionStatusSuccess:
 			workingPromo.Status.Phase = kargoapi.PromotionPhaseSucceeded
-		case directives.StatusFailure:
+		case directives.PromotionStatusFailure:
 			workingPromo.Status.Phase = kargoapi.PromotionPhaseFailed
 		}
 		if err != nil {

internal/directives/argocd_revisions.go

@@ -16,9 +16,9 @@ import (
 // have the same length as and will be indexed identically to the Application's
 // Sources slice. For any source whose desired revision cannot be determined,
 // the slice will contain an empty string at the corresponding index.
-func (a *argocdUpdateDirective) getDesiredRevisions(
+func (a *argocdUpdater) getDesiredRevisions(
 	ctx context.Context,
-	stepCtx *StepContext,
+	stepCtx *PromotionStepContext,
 	stepCfg *ArgoCDUpdateConfig,
 	stage *kargoapi.Stage,
 	update *ArgoCDAppUpdate,
@@ -60,9 +60,9 @@ func (a *argocdUpdateDirective) getDesiredRevisions(
 	return revisions, nil
 }
 
-func (a *argocdUpdateDirective) getDesiredRevisionForSource(
+func (a *argocdUpdater) getDesiredRevisionForSource(
 	ctx context.Context,
-	stepCtx *StepContext,
+	stepCtx *PromotionStepContext,
 	stage *kargoapi.Stage,
 	src *argocd.ApplicationSource,
 	desiredOrigin *kargoapi.FreightOrigin,
@@ -138,7 +138,7 @@ func (a *argocdUpdateDirective) getDesiredRevisionForSource(
 
 // findSourceUpdate finds and returns the ArgoCDSourceUpdate that targets the
 // given source. If no such update exists, it returns nil.
-func (a *argocdUpdateDirective) findSourceUpdate(
+func (a *argocdUpdater) findSourceUpdate(
 	update *ArgoCDAppUpdate,
 	src argocd.ApplicationSource,
 ) *ArgoCDAppSourceUpdate {

internal/directives/argocd_revisions_test.go

@@ -10,7 +10,7 @@ import (
 	argocdapi "github.com/akuity/kargo/internal/controller/argocd/api/v1alpha1"
 )
 
-func TestGetDesiredRevisions(t *testing.T) {
+func Test_argoCDUpdater_getDesiredRevisions(t *testing.T) {
 	testOrigin := kargoapi.FreightOrigin{
 		Kind: kargoapi.FreightOriginKindWarehouse,
 		Name: "fake-warehouse",
@@ -118,9 +118,12 @@ func TestGetDesiredRevisions(t *testing.T) {
 			want: []string{"", "v2.0.0", "v1.0.0", "v3.0.0", "", "fake-commit", "another-fake-commit", ""},
 		},
 	}
+
+	runner := &argocdUpdater{}
+
 	for _, testCase := range testCases {
 		t.Run(testCase.name, func(t *testing.T) {
-			stepCtx := &StepContext{
+			stepCtx := &PromotionStepContext{
 				Freight: kargoapi.FreightCollection{},
 			}
 			for _, freight := range testCase.freight {
@@ -143,7 +146,7 @@ func TestGetDesiredRevisions(t *testing.T) {
 					},
 				}},
 			}
-			revisions, err := (&argocdUpdateDirective{}).getDesiredRevisions(
+			revisions, err := runner.getDesiredRevisions(
 				context.Background(),
 				stepCtx,
 				stepCfg,