feat: evaluate expressions in promotion step configs (akuity#2908)

Signed-off-by: Kent Rancourt <kent.rancourt@gmail.com>
Co-authored-by: Hidde Beydals <hiddeco@users.noreply.github.com>

api/v1alpha1/promotion_types.go

@@ -86,12 +86,29 @@ type PromotionSpec struct {
 	//
 	// +kubebuilder:validation:MinLength=1
 	Freight string `json:"freight" protobuf:"bytes,2,opt,name=freight"`
+	// Vars is a list of variables that can be referenced by expressions in
+	// promotion steps.
+	Vars []PromotionVariable `json:"vars,omitempty" protobuf:"bytes,4,rep,name=vars"`
 	// Steps specifies the directives to be executed as part of this Promotion.
 	// The order in which the directives are executed is the order in which they
 	// are listed in this field.
 	Steps []PromotionStep `json:"steps,omitempty" protobuf:"bytes,3,rep,name=steps"`
 }
 
+// PromotionVariable describes a single variable that may be referenced by
+// expressions in promotion steps.
+type PromotionVariable struct {
+	// Name is the name of the variable.
+	//
+	// +kubebuilder:validation:MinLength=1
+	// +kubebuilder:validation:Pattern=^[a-zA-Z_]\w*$
+	Name string `json:"name" protobuf:"bytes,1,opt,name=name"`
+	// Value is the value of the variable. It is allowed to utilize expressions
+	// in the value.
+	// See https://docs.kargo.io/references/expression-language for details.
+	Value string `json:"value" protobuf:"bytes,2,opt,name=value"`
+}
+
 // PromotionStep describes a directive to be executed as part of a Promotion.
 type PromotionStep struct {
 	// Uses identifies a runner that can execute this step.
@@ -100,23 +117,13 @@ type PromotionStep struct {
 	Uses string `json:"uses" protobuf:"bytes,1,opt,name=uses"`
 	// As is the alias this step can be referred to as.
 	As string `json:"as,omitempty" protobuf:"bytes,2,opt,name=as"`
-	// Config is the configuration for the directive.
+	// Config is opaque configuration for the PromotionStep that is understood
+	// only by each PromotionStep's implementation. It is legal to utilize
+	// expressions in defining values at any level of this block.
+	// See https://docs.kargo.io/references/expression-language for details.
 	Config *apiextensionsv1.JSON `json:"config,omitempty" protobuf:"bytes,3,opt,name=config"`
 }
 
-// GetConfig returns the Config field as unmarshalled YAML.
-func (s *PromotionStep) GetConfig() map[string]any {
-	if s.Config == nil {
-		return nil
-	}
-
-	var config map[string]any
-	if err := yaml.Unmarshal(s.Config.Raw, &config); err != nil {
-		return nil
-	}
-	return config
-}
-
 // PromotionStatus describes the current state of the transition represented by
 // a Promotion.
 type PromotionStatus struct {

api/v1alpha1/stage_types.go

@@ -264,6 +264,9 @@ type PromotionTemplate struct {
 // for a Stage. This is a template that can be used to create a Promotion for a
 // Stage.
 type PromotionTemplateSpec struct {
+	// Vars is a list of variables that can be referenced by expressions in
+	// promotion steps.
+	Vars []PromotionVariable `json:"vars,omitempty" protobuf:"bytes,2,rep,name=vars"`
 	// Steps specifies the directives to be executed as part of a Promotion.
 	// The order in which the directives are executed is the order in which they
 	// are listed in this field.

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

@@ -89,7 +89,11 @@ spec:
                       description: As is the alias this step can be referred to as.
                       type: string
                     config:
-                      description: Config is the configuration for the directive.
+                      description: |-
+                        Config is opaque configuration for the PromotionStep that is understood
+                        only by each PromotionStep's implementation. It is legal to utilize
+                        expressions in defining values at any level of this block.
+                        See https://docs.kargo.io/references/expression-language for details.
                       x-kubernetes-preserve-unknown-fields: true
                     uses:
                       description: Uses identifies a runner that can execute this
@@ -100,6 +104,31 @@ spec:
                   - uses
                   type: object
                 type: array
+              vars:
+                description: |-
+                  Vars is a list of variables that can be referenced by expressions in
+                  promotion steps.
+                items:
+                  description: |-
+                    PromotionVariable describes a single variable that may be referenced by
+                    expressions in promotion steps.
+                  properties:
+                    name:
+                      description: Name is the name of the variable.
+                      minLength: 1
+                      pattern: ^[a-zA-Z_]\w*$
+                      type: string
+                    value:
+                      description: |-
+                        Value is the value of the variable. It is allowed to utilize expressions
+                        in the value.
+                        See https://docs.kargo.io/references/expression-language for details.
+                      type: string
+                  required:
+                  - name
+                  - value
+                  type: object
+                type: array
             required:
             - freight
             - stage

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

@@ -82,7 +82,11 @@ spec:
                                 to as.
                               type: string
                             config:
-                              description: Config is the configuration for the directive.
+                              description: |-
+                                Config is opaque configuration for the PromotionStep that is understood
+                                only by each PromotionStep's implementation. It is legal to utilize
+                                expressions in defining values at any level of this block.
+                                See https://docs.kargo.io/references/expression-language for details.
                               x-kubernetes-preserve-unknown-fields: true
                             uses:
                               description: Uses identifies a runner that can execute
@@ -94,6 +98,31 @@ spec:
                           type: object
                         minItems: 1
                         type: array
+                      vars:
+                        description: |-
+                          Vars is a list of variables that can be referenced by expressions in
+                          promotion steps.
+                        items:
+                          description: |-
+                            PromotionVariable describes a single variable that may be referenced by
+                            expressions in promotion steps.
+                          properties:
+                            name:
+                              description: Name is the name of the variable.
+                              minLength: 1
+                              pattern: ^[a-zA-Z_]\w*$
+                              type: string
+                            value:
+                              description: |-
+                                Value is the value of the variable. It is allowed to utilize expressions
+                                in the value.
+                                See https://docs.kargo.io/references/expression-language for details.
+                              type: string
+                          required:
+                          - name
+                          - value
+                          type: object
+                        type: array
                     type: object
                 required:
                 - spec

docs/docs/15-concepts.md

@@ -210,7 +210,7 @@ although other uses of this feature are anticipated in the future.
 #### Promotion Templates
 
 The `spec.promotionTemplate` field is used to describe _how_ to transition
-`Freight` into the `Stage`. The `spec.promotionTemplate.steps` field describes
+`Freight` into the `Stage`. The `spec.promotionTemplate.spec.steps` field describes
 the discrete steps of a promotion process in detail.
 
 In the following, very common example, the `promotionTemplate` describes steps