Add deprecation handling for .Updated template field

Implement error handling for deprecated .Updated template field usage
in ImageUpdateAutomation commit message templates. When users attempt
to use deprecated .Updated fields, the controller now sets a Stalled
condition with a clear error message directing them to use .Changed
fields instead, preventing infinite reconciliation loops.

This prepares for the eventual removal of the .Updated field from the
ImageUpdateAutomation API as part of GA preparation.

Signed-off-by: cappyzawa <[email protected]>

Author: cappyzawa

api/v1beta2/condition_types.go

@@ -36,4 +36,7 @@ const (
 
 	// InvalidPolicySelectorReason represents an invalid policy selector.
 	InvalidPolicySelectorReason string = "InvalidPolicySelector"
+
+	// RemovedTemplateFieldReason represents usage of removed template field.
+	RemovedTemplateFieldReason string = "RemovedTemplateField"
 )

docs/api/v1beta2/image-automation.md

@@ -735,7 +735,7 @@ github.com/fluxcd/pkg/apis/meta.ReconcileRequestStatus
 </div>
 </div>
 <h3 id="image.toolkit.fluxcd.io/v1beta2.ObservedPolicies">ObservedPolicies
-(<code>map[string]./api/v1beta2.ImageRef</code> alias)</h3>
+(<code>map[string]github.com/fluxcd/image-automation-controller/api/v1beta2.ImageRef</code> alias)</h3>
 <p>
 (<em>Appears on:</em>
 <a href="#image.toolkit.fluxcd.io/v1beta2.ImageUpdateAutomationStatus">ImageUpdateAutomationStatus</a>)

docs/spec/v1beta2/imageupdateautomations.md

@@ -374,12 +374,11 @@ spec:
         Automated image update by Flux
 ```
 
-**Deprecation Note:** The `Updated` template data available in v1beta1 API is
-deprecated. `Changed` template data is recommended for template data, as it
-accommodates for all the updates, including partial updates to just the image
-name or the tag, not just full image with name and tag update. The old templates
-will continue to work in v1beta2 API as `Updated` has not been removed yet. In
-the next API version, `Updated` may be removed.
+**Removal Note:** The `Updated` template data has been removed from the API.
+Use `Changed` template data instead, as it accommodates for all the updates,
+including partial updates to just the image name or the tag, not just full image
+with name and tag update. Templates using `Updated` will result in an error and
+the ImageUpdateAutomation will be marked as Stalled.
 
 The message template also has access to the data related to the changes made by
 the automation. The template is a [Go text template][go-text-template]. The data

internal/controller/imageupdateautomation_controller.go

@@ -481,6 +481,14 @@ func (r *ImageUpdateAutomationReconciler) reconcile(ctx context.Context, sp *pat
 
 	pushResult, err = sm.CommitAndPush(ctx, obj, policyResult, pushCfg...)
 	if err != nil {
+		// Check if error is due to removed template field usage.
+		// Set Stalled condition and return nil error to prevent requeue, allowing user to fix template.
+		if errors.Is(err, source.ErrRemovedTemplateField) {
+			conditions.MarkStalled(obj, imagev1.RemovedTemplateFieldReason, "%s", err)
+			result, retErr = ctrl.Result{}, nil
+			return
+		}
+
 		e := fmt.Errorf("failed to update source: %w", err)
 		conditions.MarkFalse(obj, meta.ReadyCondition, imagev1.GitOperationFailedReason, "%s", e)
 		result, retErr = ctrl.Result{}, e

internal/controller/imageupdateautomation_controller_test.go

@@ -71,12 +71,12 @@ const (
 Automation: {{ .AutomationObject }}
 
 Files:
-{{ range $filename, $_ := .Updated.Files -}}
+{{ range $filename, $_ := .Changed.ImageResult.Files -}}
 - {{ $filename }}
 {{ end -}}
 
 Objects:
-{{ range $resource, $_ := .Updated.Objects -}}
+{{ range $resource, $_ := .Changed.ImageResult.Objects -}}
 {{ if eq $resource.Kind "Deployment" -}}
 - {{ $resource.Kind | lower }} {{ $resource.Name | lower }}
 {{ else -}}
@@ -85,7 +85,7 @@ Objects:
 {{ end -}}
 
 Images:
-{{ range .Updated.Images -}}
+{{ range .Changed.ImageResult.Images -}}
 - {{.}} ({{.Policy.Name}})
 {{ end -}}
 `
@@ -841,6 +841,97 @@ Automation: %s/update-test
 	}
 }
 
+// TestImageUpdateAutomationReconciler_removedTemplateField tests removed .Updated template field usage.
+func TestImageUpdateAutomationReconciler_removedTemplateField(t *testing.T) {
+	g := NewWithT(t)
+	ctx := context.TODO()
+
+	policySpec := imagev1_reflect.ImagePolicySpec{
+		ImageRepositoryRef: meta.NamespacedObjectReference{
+			Name: "not-expected-to-exist",
+		},
+		Policy: imagev1_reflect.ImagePolicyChoice{
+			SemVer: &imagev1_reflect.SemVerPolicy{
+				Range: "1.x",
+			},
+		},
+	}
+	fixture := "testdata/appconfig"
+	latest := "helloworld:v1.0.0"
+
+	removedTemplate := `Commit summary
+
+Automation: {{ .AutomationObject }}
+
+Files:
+{{ range $filename, $_ := .Updated.Files -}}
+- {{ $filename }}
+{{ end -}}
+
+Objects:
+{{ range $resource, $_ := .Updated.Objects -}}
+{{ if eq $resource.Kind "Deployment" -}}
+- {{ $resource.Kind | lower }} {{ $resource.Name | lower }}
+{{ else -}}
+- {{ $resource.Kind }} {{ $resource.Name }}
+{{ end -}}
+{{ end -}}
+
+Images:
+{{ range .Updated.Images -}}
+- {{.}} ({{.Policy.Name}})
+{{ end -}}
+`
+
+	namespace, err := testEnv.CreateNamespace(ctx, "image-auto-test")
+	g.Expect(err).ToNot(HaveOccurred())
+	defer func() { g.Expect(testEnv.Delete(ctx, namespace)).To(Succeed()) }()
+
+	testWithRepoAndImagePolicy(
+		ctx, g, testEnv, namespace.Name, fixture, policySpec, latest,
+		func(g *WithT, s repoAndPolicyArgs, repoURL string, localRepo *extgogit.Repository) {
+			policyKey := types.NamespacedName{
+				Name:      s.imagePolicyName,
+				Namespace: s.namespace,
+			}
+			_ = testutil.CommitInRepo(ctx, g, repoURL, s.branch, originRemote, "Install setter marker", func(tmp string) {
+				g.Expect(testutil.ReplaceMarker(filepath.Join(tmp, "deploy.yaml"), policyKey)).To(Succeed())
+			})
+
+			preChangeCommitId := testutil.CommitIdFromBranch(localRepo, s.branch)
+			waitForNewHead(g, localRepo, s.branch, preChangeCommitId)
+			preChangeCommitId = testutil.CommitIdFromBranch(localRepo, s.branch)
+
+			updateStrategy := &imagev1.UpdateStrategy{
+				Strategy: imagev1.UpdateStrategySetters,
+			}
+			err := createImageUpdateAutomation(ctx, testEnv, "update-test", s.namespace, s.gitRepoName, s.gitRepoNamespace, s.branch, s.branch, "", removedTemplate, "", updateStrategy)
+			g.Expect(err).ToNot(HaveOccurred())
+			defer func() {
+				g.Expect(deleteImageUpdateAutomation(ctx, testEnv, "update-test", s.namespace)).To(Succeed())
+			}()
+
+			imageUpdateKey := types.NamespacedName{
+				Namespace: s.namespace,
+				Name:      "update-test",
+			}
+
+			g.Eventually(func() bool {
+				var imageUpdate imagev1.ImageUpdateAutomation
+				_ = testEnv.Get(context.TODO(), imageUpdateKey, &imageUpdate)
+				stalledCondition := apimeta.FindStatusCondition(imageUpdate.Status.Conditions, meta.StalledCondition)
+				return stalledCondition != nil &&
+					stalledCondition.Status == metav1.ConditionTrue &&
+					stalledCondition.Reason == imagev1.RemovedTemplateFieldReason &&
+					strings.Contains(stalledCondition.Message, "template uses removed '.Updated' field")
+			}, timeout).Should(BeTrue())
+
+			head, _ := localRepo.Head()
+			g.Expect(head.Hash().String()).To(Equal(preChangeCommitId))
+		},
+	)
+}
+
 func TestImageUpdateAutomationReconciler_crossNamespaceRef(t *testing.T) {
 	g := NewWithT(t)
 	policySpec := imagev1_reflect.ImagePolicySpec{

internal/source/source.go

@@ -48,13 +48,15 @@ import (
 // ErrInvalidSourceConfiguration is an error for invalid source configuration.
 var ErrInvalidSourceConfiguration = errors.New("invalid source configuration")
 
+// ErrRemovedTemplateField is an error for removed template field usage.
+var ErrRemovedTemplateField = errors.New("template uses removed '.Updated' field. Please use '.Changed' instead. See: https://fluxcd.io/flux/components/image/imageupdateautomations/#message-template")
+
 const defaultMessageTemplate = `Update from image update automation`
 
 // TemplateData is the type of the value given to the commit message
 // template.
 type TemplateData struct {
 	AutomationObject types.NamespacedName
-	Updated          update.Result
 	Changed          update.ResultV2
 	Values           map[string]string
 }
@@ -279,7 +281,6 @@ func (sm SourceManager) CommitAndPush(ctx context.Context, obj *imagev1.ImageUpd
 	// Perform a Git commit.
 	templateValues := &TemplateData{
 		AutomationObject: sm.automationObjKey,
-		Updated:          policyResult.ImageResult,
 		Changed:          policyResult,
 		Values:           obj.Spec.GitSpec.Commit.MessageTemplateValues,
 	}
@@ -356,6 +357,9 @@ func templateMsg(messageTemplate string, templateValues *TemplateData) (string,
 
 	b := &strings.Builder{}
 	if err := t.Execute(b, *templateValues); err != nil {
+		if strings.Contains(err.Error(), "can't evaluate field Updated in type source.TemplateData") {
+			return "", ErrRemovedTemplateField
+		}
 		return "", fmt.Errorf("failed to run template from spec: %w", err)
 	}
 	return b.String(), nil

internal/source/source_test.go

@@ -55,8 +55,8 @@ import (
 )
 
 const (
-	originRemote       = "origin"
-	testCommitTemplate = `Commit summary
+	originRemote              = "origin"
+	testCommitTemplateRemoved = `Commit summary
 
 Automation: {{ .AutomationObject }}
 
@@ -469,31 +469,20 @@ func test_sourceManager_CommitAndPush(t *testing.T, proto string) {
 		checkRefSpecBranch string
 	}{
 		{
-			name: "push to cloned branch with custom template",
+			name: "push to cloned branch with removed template field",
 			gitSpec: &imagev1.GitSpec{
 				Push: &imagev1.PushSpec{
 					Branch: "main",
 				},
 				Commit: imagev1.CommitSpec{
-					MessageTemplate: testCommitTemplate,
+					MessageTemplate: testCommitTemplateRemoved,
 				},
 			},
 			gitRepoReference: &sourcev1.GitRepositoryRef{
 				Branch: "main",
 			},
 			latestImage: "helloworld:1.0.1",
-			wantErr:     false,
-			wantCommitMsg: `Commit summary
-
-Automation: test-ns/test-update
-
-Files:
-- deploy.yaml
-Objects:
-- deployment test
-Images:
-- helloworld:1.0.1 (policy1)
-`,
+			wantErr:     true,
 		},
 		{
 			name: "commit with update ResultV2 template",
@@ -771,6 +760,11 @@ Testing: value
 
 			pushResult, err := sm.CommitAndPush(ctx, updateAuto, result)
 			g.Expect(err != nil).To(Equal(tt.wantErr))
+			if tt.wantErr {
+				g.Expect(pushResult).To(BeNil())
+				g.Expect(err).To(MatchError(ErrRemovedTemplateField))
+				return
+			}
 			if tt.noChange {
 				g.Expect(pushResult).To(BeNil())
 				return