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"
+
+	// DeprecatedTemplateFieldReason represents usage of deprecated template field.
+	DeprecatedTemplateFieldReason string = "DeprecatedTemplateField"
 )

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>)

internal/controller/imageupdateautomation_controller.go

@@ -481,6 +481,15 @@ 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 deprecated template field usage.
+		// Set Stalled condition and return nil error to prevent requeue, allowing user to fix template.
+		// TODO: Remove this block after .Updated template field is completely removed from the API.
+		if errors.Is(err, source.ErrDeprecatedTemplateField) {
+			conditions.MarkStalled(obj, imagev1.DeprecatedTemplateFieldReason, "%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,98 @@ Automation: %s/update-test
 	}
 }
 
+// TestImageUpdateAutomationReconciler_deprecatedTemplateField tests deprecated .Updated template field usage.
+// TODO: Remove this test function after .Updated template field is completely removed from the API.
+func TestImageUpdateAutomationReconciler_deprecatedTemplateField(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"
+
+	deprecatedTemplate := `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, "", deprecatedTemplate, "", 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.DeprecatedTemplateFieldReason &&
+					strings.Contains(stalledCondition.Message, "template uses deprecated '.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

@@ -22,6 +22,7 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
+	"regexp"
 	"strings"
 	"text/template"
 	"time"
@@ -48,8 +49,14 @@ import (
 // ErrInvalidSourceConfiguration is an error for invalid source configuration.
 var ErrInvalidSourceConfiguration = errors.New("invalid source configuration")
 
+// ErrDeprecatedTemplateField is an error for deprecated template field usage.
+var ErrDeprecatedTemplateField = errors.New("template uses deprecated '.Updated' field. Please use '.Changed' instead. See: https://fluxcd.io/flux/components/image/imageupdateautomations/#message-template")
+
 const defaultMessageTemplate = `Update from image update automation`
 
+// deprecatedUpdatedPattern matches deprecated .Updated field usage in templates
+var deprecatedUpdatedPattern = regexp.MustCompile(`\.Updated\.`)
+
 // TemplateData is the type of the value given to the commit message
 // template.
 type TemplateData struct {
@@ -346,6 +353,10 @@ func templateMsg(messageTemplate string, templateValues *TemplateData) (string,
 		messageTemplate = defaultMessageTemplate
 	}
 
+	if deprecatedUpdatedPattern.MatchString(messageTemplate) {
+		return "", ErrDeprecatedTemplateField
+	}
+
 	// Includes only functions that are guaranteed to always evaluate to the same result for given input.
 	// This removes the possibility of accidentally relying on where or when the template runs.
 	// https://github.com/Masterminds/sprig/blob/3ac42c7bc5e4be6aa534e036fb19dde4a996da2e/functions.go#L70

internal/source/source_test.go

@@ -55,8 +55,8 @@ import (
 )
 
 const (
-	originRemote       = "origin"
-	testCommitTemplate = `Commit summary
+	originRemote                 = "origin"
+	testCommitTemplateDeprecated = `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 deprecated template field",
 			gitSpec: &imagev1.GitSpec{
 				Push: &imagev1.PushSpec{
 					Branch: "main",
 				},
 				Commit: imagev1.CommitSpec{
-					MessageTemplate: testCommitTemplate,
+					MessageTemplate: testCommitTemplateDeprecated,
 				},
 			},
 			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(ErrDeprecatedTemplateField))
+				return
+			}
 			if tt.noChange {
 				g.Expect(pushResult).To(BeNil())
 				return