feat: pause auto-promotion after rollback

Signed-off-by: Jacob Boykin <jacob.boykin@akuity.io>

Author: jacobboykin

api/v1alpha1/annotations.go

@@ -6,6 +6,27 @@ const (
 	// the resource.
 	AnnotationKeyCreateActor = "kargo.akuity.io/create-actor"
 
+	// AnnotationKeyClearAutoPromotionHold is an annotation key set on a
+	// user-directed Promotion when it should clear an existing auto-promotion
+	// hold after it succeeds. The value identifies the FreightOrigin the hold
+	// applies to.
+	AnnotationKeyClearAutoPromotionHold = "kargo.akuity.io/clear-auto-promotion-hold"
+
+	// AnnotationKeyClearAutoPromotionHoldPromotion is an annotation key set
+	// alongside AnnotationKeyClearAutoPromotionHold. The value identifies the
+	// rollback Promotion recorded on the hold that should be cleared.
+	AnnotationKeyClearAutoPromotionHoldPromotion = "kargo.akuity.io/clear-auto-promotion-hold-promotion"
+
+	// AnnotationKeyClearAutoPromotionHoldPromotionUID is an annotation key set
+	// alongside AnnotationKeyClearAutoPromotionHold. The value identifies the
+	// rollback Promotion UID recorded on the hold that should be cleared.
+	AnnotationKeyClearAutoPromotionHoldPromotionUID = "kargo.akuity.io/clear-auto-promotion-hold-promotion-uid"
+
+	// AnnotationKeyClearAutoPromotionHoldCreatedAt is an annotation key set
+	// alongside AnnotationKeyClearAutoPromotionHold. The value identifies the
+	// hold creation time that should be cleared.
+	AnnotationKeyClearAutoPromotionHoldCreatedAt = "kargo.akuity.io/clear-auto-promotion-hold-created-at"
+
 	// AnnotationKeyRefresh is an annotation key that can be set on a resource
 	// to trigger a refresh of the resource by the controller. The value of the
 	// annotation is interpreted as a token, and any change to the value of the

api/v1alpha1/generated.pb.go

@@ -9,6 +9,20 @@ import (
 	"sigs.k8s.io/yaml"
 )
 
+const (
+	// PromotionSourceNonAuto denotes a Promotion created outside the Stage
+	// controller's normal auto-promotion loop. It does not necessarily mean a
+	// human created the Promotion.
+	PromotionSourceNonAuto PromotionSource = "nonAuto"
+	// PromotionSourceAuto denotes a Promotion created by Kargo's Stage
+	// controller while processing normal auto-promotion.
+	PromotionSourceAuto PromotionSource = "auto"
+)
+
+// PromotionSource identifies the actor path that created a Promotion.
+// +kubebuilder:validation:Enum=nonAuto;auto
+type PromotionSource string
+
 const (
 	// PromotionPhasePending denotes a Promotion that has not been executed yet.
 	// i.e. It is currently waiting in a queue. Queues are stage-specific and
@@ -178,6 +192,10 @@ type PromotionSpec struct {
 	// +kubebuilder:validation:Pattern=`^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$`
 	// +akuity:test-kubebuilder-pattern=KubernetesName
 	Freight string `json:"freight" protobuf:"bytes,2,opt,name=freight"`
+	// Source describes the system path that created this Promotion. The value is
+	// immutable and is used by controllers to distinguish normal auto-promotion
+	// from user-directed promotion requests.
+	Source PromotionSource `json:"source,omitempty" protobuf:"bytes,5,opt,name=source" swaggertype:"string"`
 	// Vars is a list of variables that can be referenced by expressions in
 	// promotion steps.
 	Vars []ExpressionVariable `json:"vars,omitempty" protobuf:"bytes,4,rep,name=vars"`

api/v1alpha1/generated.proto

@@ -262,9 +262,27 @@ func (f *FreightOrigin) String() string {
 	if f == nil {
 		return ""
 	}
+	// This format is persisted in annotations and status keys. Do not change it
+	// without a migration for existing resources.
 	return fmt.Sprintf("%s/%s", f.Kind, f.Name)
 }
 
+// ParseFreightOriginKey parses a canonical Freight origin key in "Kind/name"
+// form and rejects empty parts or unsupported origin kinds.
+func ParseFreightOriginKey(key string) (FreightOrigin, error) {
+	kind, name, ok := strings.Cut(key, "/")
+	if !ok || kind == "" || name == "" {
+		return FreightOrigin{}, fmt.Errorf("invalid Freight origin key %q", key)
+	}
+	origin := FreightOrigin{Kind: FreightOriginKind(kind), Name: name}
+	switch origin.Kind {
+	case FreightOriginKindWarehouse:
+		return origin, nil
+	default:
+		return FreightOrigin{}, fmt.Errorf("invalid Freight origin kind %q", kind)
+	}
+}
+
 func (f *FreightOrigin) Equals(other *FreightOrigin) bool {
 	if f == nil && other == nil {
 		return true
@@ -426,6 +444,65 @@ type StageStatus struct {
 	// This is useful for storing additional information about the Stage
 	// that can be shared across promotions, verifications, or other processes.
 	Metadata map[string]apiextensionsv1.JSON `json:"metadata,omitempty" protobuf:"bytes,15,rep,name=metadata" protobuf_key:"bytes,1,opt,name=key" protobuf_val:"bytes,2,opt,name=value"`
+	// AutoPromotionHolds pause auto-promotion for specific FreightOrigins on
+	// this Stage after a user-directed promotion intentionally selects an older
+	// piece of Freight. Each map entry pins a single origin keyed by the
+	// canonical string representation of the FreightOrigin.
+	AutoPromotionHolds map[string]AutoPromotionHold `json:"autoPromotionHolds,omitempty" protobuf:"bytes,16,rep,name=autoPromotionHolds" protobuf_key:"bytes,1,opt,name=key" protobuf_val:"bytes,2,opt,name=value"`
+}
+
+// AutoPromotionHoldState represents the lifecycle state of an
+// AutoPromotionHold.
+// +kubebuilder:validation:Enum=Pending;Active
+type AutoPromotionHoldState string
+
+const (
+	// AutoPromotionHoldStatePending indicates that the hold is waiting for
+	// its linked rollback Promotion to succeed.
+	AutoPromotionHoldStatePending AutoPromotionHoldState = "Pending"
+	// AutoPromotionHoldStateActive indicates that the hold is preserving a
+	// successful rollback.
+	AutoPromotionHoldStateActive AutoPromotionHoldState = "Active"
+)
+
+// AutoPromotionHold pins a single FreightOrigin on a Stage, pausing
+// auto-promotion for that origin after a user-directed promotion intentionally
+// selects an older piece of Freight. Other origins continue to auto-promote
+// normally. The origin is identified by the enclosing map key.
+type AutoPromotionHold struct {
+	// Freight is a reference to the Freight that was selected by the operator
+	// when the hold was created.
+	// +kubebuilder:validation:Required
+	Freight FreightReference `json:"freight" protobuf:"bytes,1,opt,name=freight"`
+	// State is the current lifecycle state of the hold.
+	// +kubebuilder:validation:Required
+	State AutoPromotionHoldState `json:"state" protobuf:"bytes,2,opt,name=state" swaggertype:"string"`
+	// PromotionName is the name of the rollback Promotion associated
+	// with this hold, when applicable.
+	PromotionName string `json:"promotionName,omitempty" protobuf:"bytes,3,opt,name=promotionName"`
+	// PromotionUID is the UID of the rollback Promotion. Used to
+	// prevent an older failed rollback from clearing a newer hold.
+	PromotionUID string `json:"promotionUID,omitempty" protobuf:"bytes,4,opt,name=promotionUID"`
+	// Actor is an identifier for the user who caused the hold to be created.
+	Actor string `json:"actor,omitempty" protobuf:"bytes,5,opt,name=actor"`
+	// Reason is a free-form human-readable explanation of why the hold was
+	// created.
+	Reason string `json:"reason,omitempty" protobuf:"bytes,6,opt,name=reason"`
+	// CreatedAt is the time at which the hold was created.
+	CreatedAt *metav1.Time `json:"createdAt,omitempty" protobuf:"bytes,7,opt,name=createdAt"`
+}
+
+// GetAutoPromotionHold returns the AutoPromotionHold for the given origin, if
+// one exists. The second return value indicates whether a hold was found.
+func (s *StageStatus) GetAutoPromotionHold(origin FreightOrigin) (AutoPromotionHold, bool) {
+	if s == nil {
+		return AutoPromotionHold{}, false
+	}
+	hold, ok := s.AutoPromotionHolds[origin.String()]
+	if !ok {
+		return AutoPromotionHold{}, false
+	}
+	return hold, true
 }
 
 // GetConditions implements the conditions.Getter interface.

api/v1alpha1/promotion_types.go

@@ -974,6 +974,119 @@ func TestChartDeepEquals(t *testing.T) {
 	}
 }
 
+func TestFreightOrigin_String(t *testing.T) {
+	origin := &FreightOrigin{
+		Kind: FreightOriginKindWarehouse,
+		Name: "fake-warehouse",
+	}
+
+	require.Equal(t, "Warehouse/fake-warehouse", origin.String())
+	require.Empty(t, (*FreightOrigin)(nil).String())
+}
+
+func TestParseFreightOriginKey(t *testing.T) {
+	testCases := []struct {
+		name           string
+		key            string
+		expectedOrigin FreightOrigin
+		expectErr      bool
+	}{
+		{
+			name: "valid warehouse origin",
+			key:  "Warehouse/fake-warehouse",
+			expectedOrigin: FreightOrigin{
+				Kind: FreightOriginKindWarehouse,
+				Name: "fake-warehouse",
+			},
+		},
+		{
+			name:      "missing slash",
+			key:       "Warehouse",
+			expectErr: true,
+		},
+		{
+			name:      "missing kind",
+			key:       "/fake-warehouse",
+			expectErr: true,
+		},
+		{
+			name:      "missing name",
+			key:       "Warehouse/",
+			expectErr: true,
+		},
+		{
+			name:      "unknown kind",
+			key:       "Stage/fake-stage",
+			expectErr: true,
+		},
+	}
+
+	for _, testCase := range testCases {
+		t.Run(testCase.name, func(t *testing.T) {
+			origin, err := ParseFreightOriginKey(testCase.key)
+			if testCase.expectErr {
+				require.Error(t, err)
+				return
+			}
+			require.NoError(t, err)
+			require.Equal(t, testCase.expectedOrigin, origin)
+		})
+	}
+}
+
+func TestStageStatus_GetAutoPromotionHold(t *testing.T) {
+	origin := FreightOrigin{
+		Kind: FreightOriginKindWarehouse,
+		Name: "fake-warehouse",
+	}
+	hold := AutoPromotionHold{
+		Freight: FreightReference{Name: "fake-freight", Origin: origin},
+		State:   AutoPromotionHoldStateActive,
+	}
+
+	testCases := []struct {
+		name       string
+		status     *StageStatus
+		assertions func(*testing.T, AutoPromotionHold, bool)
+	}{
+		{
+			name:   "nil status",
+			status: nil,
+			assertions: func(t *testing.T, hold AutoPromotionHold, ok bool) {
+				require.False(t, ok)
+				require.Empty(t, hold)
+			},
+		},
+		{
+			name: "hold exists",
+			status: &StageStatus{
+				AutoPromotionHolds: map[string]AutoPromotionHold{
+					origin.String(): hold,
+				},
+			},
+			assertions: func(t *testing.T, actual AutoPromotionHold, ok bool) {
+				require.True(t, ok)
+				require.Equal(t, hold, actual)
+			},
+		},
+		{
+			name:   "hold does not exist",
+			status: &StageStatus{},
+			assertions: func(t *testing.T, hold AutoPromotionHold, ok bool) {
+				require.False(t, ok)
+				require.Empty(t, hold)
+			},
+		},
+	}
+
+	for _, testCase := range testCases {
+		t.Run(testCase.name, func(t *testing.T) {
+			hold, ok := testCase.status.GetAutoPromotionHold(origin)
+			testCase.assertions(t, hold, ok)
+		})
+	}
+}
+
 func TestStageStatus_UpsertMetadata(t *testing.T) {
 	testCases := []struct {
 		name         string