chore(backport release-1.3): fix: Long Stage names result in AnalysisRun creation failures during promotion (#3553)

Co-authored-by: Aidan Rowe <[email protected]>

Author: akuitybot

api/v1alpha1/annotations.go

@@ -37,6 +37,10 @@ const (
 	// of the annotation should be in the format of "<project>:<stage>".
 	AnnotationKeyAuthorizedStage = "kargo.akuity.io/authorized-stage"
 
+	// 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"
+
 	// AnnotationValueTrue is a value that can be set on an annotation to
 	// indicate that it applies.
 	AnnotationValueTrue = "true"

api/v1alpha1/labels.go

@@ -20,7 +20,6 @@ const (
 	// Kargo core API
 	FreightCollectionLabelKey = "kargo.akuity.io/freight-collection"
 	ProjectLabelKey           = "kargo.akuity.io/project"
-	PromotionLabelKey         = "kargo.akuity.io/promotion"
 	ShardLabelKey             = "kargo.akuity.io/shard"
 	StageLabelKey             = "kargo.akuity.io/stage"
 

docs/docs/50-user-guide/20-how-to-guides/60-verification.md

@@ -145,8 +145,9 @@ metadata:
   generation: 3
   labels:
     kargo.akuity.io/freight-collection: 55d452301040a73e9fd05289b1f8ddbec1791222
-    kargo.akuity.io/promotion: dev.01jjpfgfwkzk18k7cyq61jehf4.319ddec
     kargo.akuity.io/stage: dev
+  annotations:
+    kargo.akuity.io/promotion: dev.01jjpfgfwkzk18k7cyq61jehf4.319ddec
   name: dev.01jjqaq7qacfn766tcp1nqz2zv.55d4523
   namespace: guestbook
   ownerReferences:

internal/controller/stages/regular_stages.go

@@ -1194,7 +1194,7 @@ func (r *RegularStageReconciler) recordFreightVerificationEvent(
 			)
 		}
 		// AnalysisRun that triggered by a Promotion contains the Promotion name
-		if promoName, ok := ar.Labels[kargoapi.PromotionLabelKey]; ok {
+		if promoName, ok := ar.Annotations[kargoapi.AnnotationKeyPromotion]; ok {
 			annotations[kargoapi.AnnotationKeyEventPromotionName] = promoName
 		}
 	}
@@ -1333,8 +1333,8 @@ func (r *RegularStageReconciler) startVerification(
 	}
 	if curVI == nil || (req.ForID(curVI.ID) && req.ControlPlane && req.Actor != "") {
 		if stage.Status.LastPromotion != nil {
-			builderOpts = append(builderOpts, rollouts.WithExtraLabels{
-				kargoapi.PromotionLabelKey: stage.Status.LastPromotion.Name,
+			builderOpts = append(builderOpts, rollouts.WithExtraAnnotations{
+				kargoapi.AnnotationKeyPromotion: stage.Status.LastPromotion.Name,
 			})
 		}
 	}

internal/controller/stages/regular_stages_test.go

@@ -3033,8 +3033,8 @@ func TestRegularStageReconciler_recordFreightVerificationEvent(t *testing.T) {
 					ObjectMeta: metav1.ObjectMeta{
 						Name:      "test-analysis",
 						Namespace: "test-project",
-						Labels: map[string]string{
-							kargoapi.PromotionLabelKey: "test-promotion",
+						Annotations: map[string]string{
+							kargoapi.AnnotationKeyPromotion: "test-promotion",
 						},
 					},
 				},
@@ -3370,7 +3370,7 @@ func TestRegularStageReconciler_startVerification(t *testing.T) {
 					Namespace: vi.AnalysisRun.Namespace,
 					Name:      vi.AnalysisRun.Name,
 				}, ar))
-				assert.Equal(t, "test-promotion", ar.Labels[kargoapi.PromotionLabelKey])
+				assert.Equal(t, "test-promotion", ar.Annotations[kargoapi.AnnotationKeyPromotion])
 			},
 		},
 		{

internal/rollouts/analysis_run_builder.go

@@ -66,6 +66,7 @@ func (b *AnalysisRunBuilder) Build(
 		b.generateName(opts.NamePrefix, opts.NameSuffix),
 		cfg.AnalysisRunMetadata,
 		opts.ExtraLabels,
+		opts.ExtraAnnotations,
 	)
 
 	analysisTemplates, clusterAnalysisTemplates, err := b.getAnalysisTemplates(
@@ -121,18 +122,24 @@ func (b *AnalysisRunBuilder) generateName(prefix, suffix string) string {
 func (b *AnalysisRunBuilder) buildMetadata(
 	namespace, name string,
 	metadata *kargoapi.AnalysisRunMetadata,
-	extraLabels map[string]string,
+	extraLabels, extraAnnotations map[string]string,
 ) metav1.ObjectMeta {
-	var annotations map[string]string
+	annotations := make(map[string]string)
 	labels := make(map[string]string)
 
 	if metadata != nil {
-		annotations = metadata.Annotations
+		if metadata.Annotations != nil {
+			maps.Copy(annotations, metadata.Annotations)
+		}
 		if metadata.Labels != nil {
 			maps.Copy(labels, metadata.Labels)
 		}
 	}
 
+	if extraAnnotations != nil {
+		maps.Copy(annotations, extraAnnotations)
+	}
+
 	if extraLabels != nil {
 		maps.Copy(labels, extraLabels)
 	}

internal/rollouts/analysis_run_builder_test.go

@@ -359,12 +359,13 @@ func TestAnalysisRunBuilder_buildMetadata(t *testing.T) {
 	}
 
 	tests := []struct {
-		name        string
-		namespace   string
-		objName     string
-		metadata    *kargoapi.AnalysisRunMetadata
-		extraLabels map[string]string
-		assertions  func(*testing.T, metav1.ObjectMeta)
+		name             string
+		namespace        string
+		objName          string
+		metadata         *kargoapi.AnalysisRunMetadata
+		extraLabels      map[string]string
+		extraAnnotations map[string]string
+		assertions       func(*testing.T, metav1.ObjectMeta)
 	}{
 		{
 			name:      "basic metadata",
@@ -377,7 +378,7 @@ func TestAnalysisRunBuilder_buildMetadata(t *testing.T) {
 			},
 		},
 		{
-			name:      "with metadata and extra labels",
+			name:      "with metadata, extra labels and extra annotations",
 			namespace: "test-ns",
 			objName:   "test-name",
 			metadata: &kargoapi.AnalysisRunMetadata{
@@ -391,9 +392,13 @@ func TestAnalysisRunBuilder_buildMetadata(t *testing.T) {
 			extraLabels: map[string]string{
 				"extra": "value",
 			},
+			extraAnnotations: map[string]string{
+				"extra2": "value2",
+			},
 			assertions: func(t *testing.T, meta metav1.ObjectMeta) {
 				assert.Equal(t, "value1", meta.Labels["label1"])
 				assert.Equal(t, "value", meta.Labels["extra"])
+				assert.Equal(t, "value2", meta.Annotations["extra2"])
 				assert.Equal(t, "value1", meta.Annotations["anno1"])
 				assert.Equal(t, "test-controller", meta.Labels[controllerInstanceIDLabelKey])
 			},
@@ -402,7 +407,7 @@ func TestAnalysisRunBuilder_buildMetadata(t *testing.T) {
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			result := builder.buildMetadata(tt.namespace, tt.objName, tt.metadata, tt.extraLabels)
+			result := builder.buildMetadata(tt.namespace, tt.objName, tt.metadata, tt.extraLabels, tt.extraAnnotations)
 			tt.assertions(t, result)
 		})
 	}

internal/rollouts/options.go

@@ -31,6 +31,7 @@ type AnalysisRunOptions struct {
 	NamePrefix       string
 	NameSuffix       string
 	ExtraLabels      map[string]string
+	ExtraAnnotations map[string]string
 	Owners           []Owner
 	ExpressionConfig *ArgumentEvaluationConfig
 }
@@ -100,6 +101,18 @@ func (o WithExtraLabels) ApplyToAnalysisRun(opts *AnalysisRunOptions) {
 	opts.ExtraLabels = o
 }
 
+// WithExtraAnnotations sets the extra labels for the AnalysisRun. It can be passed
+// multiple times to add more annotations.
+type WithExtraAnnotations map[string]string
+
+func (o WithExtraAnnotations) ApplyToAnalysisRun(opts *AnalysisRunOptions) {
+	if opts.ExtraAnnotations != nil {
+		maps.Copy(opts.ExtraAnnotations, o)
+		return
+	}
+	opts.ExtraAnnotations = o
+}
+
 // WithOwner sets the owner for the AnalysisRun. It can be passed multiple times
 // to add more owners.
 type WithOwner Owner

internal/rollouts/options_test.go

@@ -74,6 +74,31 @@ func TestAnalysisRunOptions(t *testing.T) {
 				}, opts.ExtraLabels)
 			},
 		},
+		{
+			name: "extra annotations: single set",
+			options: []AnalysisRunOption{
+				WithExtraAnnotations{"key1": "value1", "key2": "value2"},
+			},
+			assertions: func(t *testing.T, opts *AnalysisRunOptions) {
+				assert.Equal(t, map[string]string{
+					"key1": "value1",
+					"key2": "value2",
+				}, opts.ExtraAnnotations)
+			},
+		},
+		{
+			name: "extra annotations: multiple sets are merged",
+			options: []AnalysisRunOption{
+				WithExtraAnnotations{"key1": "value1"},
+				WithExtraAnnotations{"key2": "value2"},
+			},
+			assertions: func(t *testing.T, opts *AnalysisRunOptions) {
+				assert.Equal(t, map[string]string{
+					"key1": "value1",
+					"key2": "value2",
+				}, opts.ExtraAnnotations)
+			},
+		},
 		{
 			name: "single owner",
 			options: []AnalysisRunOption{