feat: (cluster) Promotion tasks (akuity#3121)

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

api/v1alpha1/cluster_promotion_task_types.go

@@ -0,0 +1,27 @@
+package v1alpha1
+
+import metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+
+// +kubebuilder:resource:scope=Cluster,shortName={clusterpromotask,clusterpromotasks}
+// +kubebuilder:object:root=true
+// +kubebuilder:printcolumn:name=Age,type=date,JSONPath=`.metadata.creationTimestamp`
+
+type ClusterPromotionTask struct {
+	metav1.TypeMeta   `json:",inline"`
+	metav1.ObjectMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"`
+
+	// Spec describes the desired transition of a specific Stage into a specific
+	// Freight.
+	//
+	// +kubebuilder:validation:Required
+	Spec PromotionTaskSpec `json:"spec" protobuf:"bytes,2,opt,name=spec"`
+}
+
+// +kubebuilder:object:root=true
+
+// ClusterPromotionTaskList contains a list of PromotionTasks.
+type ClusterPromotionTaskList struct {
+	metav1.TypeMeta `json:",inline"`
+	metav1.ListMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"`
+	Items           []ClusterPromotionTask `json:"items" protobuf:"bytes,2,rep,name=items"`
+}

api/v1alpha1/groupversion_info.go

@@ -27,6 +27,8 @@ var (
 // addKnownTypes adds the set of types defined in this package to the supplied scheme.
 func addKnownTypes(scheme *runtime.Scheme) error {
 	scheme.AddKnownTypes(GroupVersion,
+		&ClusterPromotionTask{},
+		&ClusterPromotionTaskList{},
 		&Freight{},
 		&FreightList{},
 		&Stage{},
@@ -35,6 +37,8 @@ func addKnownTypes(scheme *runtime.Scheme) error {
 		&ProjectList{},
 		&Promotion{},
 		&PromotionList{},
+		&PromotionTask{},
+		&PromotionTaskList{},
 		&Warehouse{},
 		&WarehouseList{},
 	)

api/v1alpha1/promotion_task_types.go

@@ -0,0 +1,44 @@
+package v1alpha1
+
+import (
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+)
+
+// +kubebuilder:resource:shortName={promotask,promotasks}
+// +kubebuilder:object:root=true
+// +kubebuilder:printcolumn:name=Age,type=date,JSONPath=`.metadata.creationTimestamp`
+
+type PromotionTask struct {
+	metav1.TypeMeta   `json:",inline"`
+	metav1.ObjectMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"`
+
+	// Spec describes the composition of a PromotionTask, including the
+	// variables available to the task and the steps.
+	//
+	// +kubebuilder:validation:Required
+	Spec PromotionTaskSpec `json:"spec" protobuf:"bytes,2,opt,name=spec"`
+}
+
+type PromotionTaskSpec struct {
+	// Vars specifies the variables available to the PromotionTask. The
+	// values of these variables are the default values that can be
+	// overridden by the step referencing the task.
+	Vars []PromotionVariable `json:"vars,omitempty" protobuf:"bytes,1,rep,name=vars"`
+	// Steps specifies the directives to be executed as part of this
+	// PromotionTask. The steps as defined here are inflated into a
+	// Promotion when it is built from a PromotionTemplate.
+	//
+	// +kubebuilder:validation:Required
+	// +kubebuilder:validation:MinItems=1
+	// +kubebuilder:validation:items:XValidation:message="PromotionTask step must have uses set and must not reference another task",rule="has(self.uses) && !has(self.task)"
+	Steps []PromotionStep `json:"steps" protobuf:"bytes,2,rep,name=steps"`
+}
+
+// +kubebuilder:object:root=true
+
+// PromotionTaskList contains a list of PromotionTasks.
+type PromotionTaskList struct {
+	metav1.TypeMeta `json:",inline"`
+	metav1.ListMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"`
+	Items           []PromotionTask `json:"items" protobuf:"bytes,2,rep,name=items"`
+}

api/v1alpha1/promotion_types.go

@@ -1,6 +1,7 @@
 package v1alpha1
 
 import (
+	"fmt"
 	"time"
 
 	apiextensionsv1 "k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1"
@@ -80,21 +81,30 @@ type PromotionSpec struct {
 	// applies. The Stage referenced by this field MUST be in the same
 	// namespace as the Promotion.
 	//
+	// +kubebuilder:validation:Required
 	// +kubebuilder:validation:MinLength=1
+	// +kubebuilder:validation:MaxLength=253
 	// +kubebuilder:validation:Pattern=^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$
 	Stage string `json:"stage" protobuf:"bytes,1,opt,name=stage"`
 	// Freight specifies the piece of Freight to be promoted into the Stage
 	// referenced by the Stage field.
 	//
+	// +kubebuilder:validation:Required
 	// +kubebuilder:validation:MinLength=1
+	// +kubebuilder:validation:MaxLength=253
+	// +kubebuilder:validation:Pattern=^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$
 	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"`
+	//
+	// +kubebuilder:validation:Required
+	// +kubebuilder:validation:MinItems=1
+	// +kubebuilder:validation:items:XValidation:message="Promotion step must have uses set and must not reference a task",rule="has(self.uses) && !has(self.task)"
+	Steps []PromotionStep `json:"steps" protobuf:"bytes,3,rep,name=steps"`
 }
 
 // PromotionVariable describes a single variable that may be referenced by
@@ -108,7 +118,25 @@ type PromotionVariable struct {
 	// 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"`
+	Value string `json:"value,omitempty" protobuf:"bytes,2,opt,name=value"`
+}
+
+// PromotionTaskReference describes a reference to a PromotionTask.
+type PromotionTaskReference struct {
+	// Name is the name of the (Cluster)PromotionTask.
+	//
+	// +kubebuilder:validation:Required
+	// +kubebuilder:validation:MinLength=1
+	// +kubebuilder:validation:MaxLength=253
+	// +kubebuilder:validation:Pattern=^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$
+	Name string `json:"name" protobuf:"bytes,1,opt,name=name"`
+
+	// Kind is the type of the PromotionTask. Can be either PromotionTask or
+	// ClusterPromotionTask, default is PromotionTask.
+	//
+	// +kubebuilder:validation:Optional
+	// +kubebuilder:validation:Enum=PromotionTask;ClusterPromotionTask
+	Kind string `json:"kind,omitempty" protobuf:"bytes,2,opt,name=kind"`
 }
 
 // PromotionStepRetry describes the retry policy for a PromotionStep.
@@ -171,19 +199,42 @@ func (r *PromotionStepRetry) GetErrorThreshold(fallback uint32) uint32 {
 type PromotionStep struct {
 	// Uses identifies a runner that can execute this step.
 	//
+	// +kubebuilder:validation:Optional
 	// +kubebuilder:validation:MinLength=1
-	Uses string `json:"uses" protobuf:"bytes,1,opt,name=uses"`
+	Uses string `json:"uses,omitempty" protobuf:"bytes,1,opt,name=uses"`
+	// Task is a reference to a PromotionTask that should be inflated into a
+	// Promotion when it is built from a PromotionTemplate.
+	Task *PromotionTaskReference `json:"task,omitempty" protobuf:"bytes,5,opt,name=task"`
 	// As is the alias this step can be referred to as.
 	As string `json:"as,omitempty" protobuf:"bytes,2,opt,name=as"`
 	// Retry is the retry policy for this step.
 	Retry *PromotionStepRetry `json:"retry,omitempty" protobuf:"bytes,4,opt,name=retry"`
+	// Vars is a list of variables that can be referenced by expressions in
+	// the step's Config. The values override the values specified in the
+	// PromotionSpec.
+	Vars []PromotionVariable `json:"vars,omitempty" protobuf:"bytes,6,rep,name=vars"`
 	// 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"`
 }
 
+// GetAlias returns the As field, or a default value in the form of "step-<i>"
+// or "task-<i>" if the As field is empty. The index i is provided as an
+// argument to this method and should be the index of the PromotionStep in the
+// list it belongs to.
+func (s *PromotionStep) GetAlias(i int) string {
+	switch {
+	case s.As != "":
+		return s.As
+	case s.Task != nil:
+		return fmt.Sprintf("task-%d", i)
+	default:
+		return fmt.Sprintf("step-%d", i)
+	}
+}
+
 // PromotionStatus describes the current state of the transition represented by
 // a Promotion.
 type PromotionStatus struct {

api/v1alpha1/stage_types.go

@@ -298,6 +298,7 @@ type PromotionTemplateSpec struct {
 	// are listed in this field.
 	//
 	// +kubebuilder:validation:MinItems=1
+	// +kubebuilder:validation:items:XValidation:message="PromotionTemplate step must have exactly one of uses or task set",rule="(has(self.uses) ? !has(self.task) : has(self.task))"
 	Steps []PromotionStep `json:"steps,omitempty" protobuf:"bytes,1,rep,name=steps"`
 }