feat: add field-level custom_sync generator config (#732)

## Description

Some fields are managed by an AWS API separate from the resource's `Update` operation — tags via `CreateOrUpdateTags`, a logging configuration via its own `Put` call. Controllers reconcile these today by hand-writing an `sdk_update_pre_build_request` hook that invokes a sync function and then short-circuits out of `sdkUpdate` when nothing else differs.

Every controller doing this duplicates the same block. Worse, adding a second such field means widening the existing `DifferentExcept` call by hand, and forgetting to makes the resource silently stop applying legitimate updates, with no error surfaced anywhere.

This PR adds `custom_sync` as a field-level config that generates the boilerplate.

```yaml
resources:
  AutoScalingGroup:
    fields:
      Tags:
        custom_sync: {}
```

The sync function itself stays hand-written. It's a method on `resourceManager`, matching every other seam where generated code calls user-supplied code (`custom_implementation`, `set_output_custom_method_name`, and so on):

```go
func (rm *resourceManager) syncTags(
    ctx context.Context, desired *resource, latest *resource,
) error
```

The method name is always `sync<FieldName>` and is not configurable, so it's identical across every controller and can be found from the field name alone. `CustomSyncConfig` is an empty struct rather than a bool, so options can be added later without breaking the `generator.yaml` files that adopt `custom_sync: {}` now — promoting a bool to a struct would break under the strict unmarshalling `config.New` performs.

## Generated code

Into `sdkUpdate`:

```go
	updatedDesired := desired.DeepCopy()
	updatedDesired.SetStatus(latest)
	if delta.DifferentAt("Spec.Tags") {
		err = rm.syncTags(ctx, desired, latest)
		if err != nil {
			return nil, err
		}
	}
	if !delta.DifferentExcept("Spec.Tags") {
		return rm.concreteResource(updatedDesired), nil
	}
```

Into `sdkCreate`:

```go
	if ko.Spec.Tags != nil {
		msg := "Secondary sync required; resource will be requeued"
		ackcondition.SetSynced(&resource{ko}, corev1.ConditionFalse, &msg, nil)
	}
```

A `custom_sync` field is only ever applied in the update path, so immediately after create it exists in Spec but has not been pushed to AWS. Marking the resource unsynced makes the runtime requeue after `requeue.DefaultRequeueAfterDuration` rather than waiting for the full resync period, and the condition message tells the user a further sync is coming without their involvement.

The message is a generic constant rather than a list of the pending field paths. The nil checks guarding it are evaluated at runtime, but a generated message can only be assembled from every configured field, so naming them would over-report whenever a user populates only a subset.

With multiple `custom_sync` fields, the create-path guard collapses into one block, since `SetSynced` overwrites rather than accumulates:

```go
	if ko.Spec.LogDeliveryConfigurations != nil || ko.Spec.Tags != nil {
		msg := "Secondary sync required; resource will be requeued"
		ackcondition.SetSynced(&resource{ko}, corev1.ConditionFalse, &msg, nil)
	}
```

On the update side, all paths land in a single `DifferentExcept` call:

```go
	if !delta.DifferentExcept("Spec.LogDeliveryConfigurations", "Spec.Tags") {
```

That auto-widening is the main argument for generating this rather than documenting a snippet.

## Placement

Position in `sdk_update.go.tpl` is load-bearing in both directions, and is recorded in a comment on `CustomSyncUpdate`:

- **After** the `updateable.when` guard, so a resource in a state where mutations aren't allowed is requeued before any out-of-band API call is made, and so the short-circuit can't return success past the guard.
- **Before** the Update operation's `custom_implementation`, which returns from `sdkUpdate` directly and would otherwise skip the sync entirely.

## Validation

Rejected at generation time, since each otherwise produces a controller that compiles but misbehaves at runtime:

| Config | Why it's rejected |
| --- | --- |
| `custom_sync` on a nested field | Emitted code builds a `Spec.<Field>` delta path and a nil check off `ko.Spec` |
| `custom_sync` with `is_read_only` | Field lands in Status, where there's no desired value to sync toward |
| `custom_sync` with `compare.is_ignored` | Field never enters the delta, so the sync never runs and the short-circuit fires every reconcile |
| `custom_sync` with no Update operation | Generated code lives in `sdkUpdate`, so the sync would never be called |

## Testing

`make test` passes — 15 packages, no failures.

New unit tests cover the emitters (single field, two fields, and the no-config inert case) and the model accessors plus all validation errors. Fixtures are added under `pkg/testdata/models/apis/elasticache/0000-00-00/`.

Verified end to end by regenerating `autoscaling-controller`, which has exactly this pattern hand-written today:

- With no `custom_sync` configured, generated `sdk.go` is **byte-identical** to before, confirming the emitters are inert for resources that don't use the feature.
- With `custom_sync` on `Tags` and both hand-written hook templates deleted, the generated code matches what those hooks produced. The controller builds and its tests pass.
- Placement relative to `updateable.when` was confirmed by temporarily adding a guard to `AutoScalingGroup` and inspecting the generated output.

## Notes for reviewers

- Ordering across multiple `custom_sync` fields is alphabetical, which keeps generated output stable. Config-driven ordering is deferred until a resource needs it; note that YAML document order isn't recoverable here, since `ResourceConfig.Fields` is a map and the loader routes through `sigs.k8s.io/yaml`. An explicit `order:` key would be the way to add it.
- `custom_sync` is restricted to top-level Spec fields. Beyond the codegen reasons, `DifferentExcept` matches with `Path.Contains`, so allowing nested paths would let one diff match two except-paths and skew the count.
- No test asserts template placement, since the emitters are unit-tested in isolation. Happy to add a rendered-output assertion if you'd like that ordering pinned.

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Author: gustavodiaz7722

pkg/config/field.go

@@ -275,6 +275,50 @@ type CompareFieldConfig struct {
 	PreDeleteInclude bool `json:"pre_delete_include"`
 }
 
+// CustomSyncConfig instructs the code generator that the field is not
+// reconciled by the resource's normal Update operation, but instead by a
+// hand-written sync function that the controller author implements.
+//
+// The field's value is typically managed by a separate AWS API (tags via
+// CreateTags/DeleteTags, a scaling configuration via its own Put* call, and so
+// on), so it cannot be set through the resource's Update input shape. Setting
+// this config makes the code generator emit the boilerplate that invokes the
+// sync function from sdkUpdate, and that marks the resource unsynced after
+// create so a follow-up reconcile applies the field.
+//
+// The code generator does NOT generate the sync function itself. The author
+// implements it as a method on the resource manager in the resource's hooks.go,
+// which is how every other hand-written seam in the generated code is shaped:
+//
+//	func (rm *resourceManager) sync<Field>(
+//	    ctx context.Context,
+//	    desired *resource,
+//	    latest *resource,
+//	) error
+//
+// The receiver gives the implementation access to rm.sdkapi and rm.metrics, so
+// no additional plumbing is needed to make API calls or record them.
+//
+// Given a Tags field, the generator emits a call to `syncTags` and expects
+// `syncTags` to exist. For example:
+//
+// resources:
+//
+//	AutoScalingGroup:
+//	  fields:
+//	    Tags:
+//	      custom_sync: {}
+//
+// The struct is intentionally empty. Presence of the `custom_sync` key is the
+// entire configuration, and the sync method name is always derived from the
+// field name so that it is identical across every controller.
+//
+// It is declared as a struct rather than a bool so that options can be added
+// later without breaking the generator.yaml files that adopt it now: promoting a
+// bool to a struct would be a breaking change under the strict unmarshalling
+// config.New performs.
+type CustomSyncConfig struct{}
+
 // PrintFieldConfig instructs the code generator how to handle kubebuilder:printcolumn
 // comment marker generation. If this struct is not nil, the field will be added to the
 // columns of `kubectl get` response.
@@ -459,6 +503,11 @@ type FieldConfig struct {
 	// References instructs the code generator how to refer this field from
 	// other custom resource
 	References *ReferencesConfig `json:"references,omitempty"`
+	// CustomSync instructs the code generator that this field is reconciled by
+	// a hand-written sync function rather than by the resource's Update
+	// operation, and that the boilerplate invoking that function should be
+	// generated into sdkUpdate.
+	CustomSync *CustomSyncConfig `json:"custom_sync,omitempty"`
 	// Type *overrides* the inferred Go type of the field. This is required for
 	// custom fields that are not inferred either as a Create Input/Output
 	// shape or via the SourceFieldConfig attribute.

pkg/generate/ack/controller.go

@@ -164,6 +164,12 @@ var (
 		"GoCodeResourceIsDeletable": func(r *ackmodel.CRD, resVarName string, indentLevel int) (string, error) {
 			return code.ResourceIsDeletable(r.Config(), r, resVarName, indentLevel)
 		},
+		"GoCodeCustomSyncUpdate": func(r *ackmodel.CRD, desiredVarName string, latestVarName string, deltaVarName string, indentLevel int) string {
+			return code.CustomSyncUpdate(r, desiredVarName, latestVarName, deltaVarName, indentLevel)
+		},
+		"GoCodeCustomSyncCreate": func(r *ackmodel.CRD, koVarName string, indentLevel int) string {
+			return code.CustomSyncCreate(r, koVarName, indentLevel)
+		},
 		"GoCodeCompareStruct": func(r *ackmodel.CRD, shape *awssdkmodel.Shape, deltaVarName string, sourceVarName string, targetVarName string, fieldPath string, indentLevel int) (string, error) {
 			return code.CompareStruct(r.Config(), r, nil, shape, deltaVarName, sourceVarName, targetVarName, fieldPath, indentLevel)
 		},

pkg/generate/code/custom_sync.go

@@ -0,0 +1,206 @@
+// Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License"). You may
+// not use this file except in compliance with the License. A copy of the
+// License is located at
+//
+//     http://aws.amazon.com/apache2.0/
+//
+// or in the "license" file accompanying this file. This file is distributed
+// on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+// express or implied. See the License for the specific language governing
+// permissions and limitations under the License.
+
+package code
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/aws-controllers-k8s/code-generator/pkg/model"
+)
+
+// customSyncPendingMessage is the Synced condition message set after create when
+// a resource has `custom_sync` fields still to be applied.
+//
+// It is deliberately generic rather than naming the pending fields. The nil
+// checks that guard it are evaluated at runtime, but a generated message can
+// only be built from every configured field, so naming them would over-report
+// whenever a user populates only some of them.
+const customSyncPendingMessage = "Secondary sync required; resource will be requeued"
+
+// CustomSyncUpdate returns Go code that invokes the hand-written sync function
+// for each of the resource's `custom_sync` Spec fields, and then short-circuits
+// out of sdkUpdate when those fields are the only ones that differ.
+//
+// Fields configured with `custom_sync` are managed by a separate AWS API rather
+// than by the resource's Update operation, so when nothing else has changed
+// there is no Update call left to make. The generated code returns the desired
+// state with the observed status grafted on, which is what the reconciler
+// expects back from Update.
+//
+// All `custom_sync` fields on the resource are collected into a single
+// DifferentExcept call. That is the main reason this is generated rather than
+// hand-written: adding a second out-of-band field to a hand-written hook
+// requires widening the existing DifferentExcept, and forgetting to do so makes
+// the resource silently short-circuit out of legitimate updates.
+//
+// Placement in sdk_update.go.tpl is load-bearing. This block must come AFTER
+// the `updateable.when` guard, so that a resource in a state where mutations
+// are not allowed is requeued before any out-of-band API call is made, and so
+// that the short-circuit below cannot return success past the guard. It must
+// come BEFORE the Update operation's `custom_implementation`, which returns
+// from sdkUpdate directly and would otherwise skip the sync entirely.
+//
+// The empty string is returned when the resource has no `custom_sync` fields.
+//
+// Sample output:
+//
+//	updatedDesired := desired.DeepCopy()
+//	updatedDesired.SetStatus(latest)
+//	if delta.DifferentAt("Spec.Tags") {
+//	    err = rm.syncTags(ctx, desired, latest)
+//	    if err != nil {
+//	        return nil, err
+//	    }
+//	}
+//	if !delta.DifferentExcept("Spec.Tags") {
+//	    return rm.concreteResource(updatedDesired), nil
+//	}
+func CustomSyncUpdate(
+	r *model.CRD,
+	// desired resource variable name — "desired" for sdkUpdate
+	desiredVarName string,
+	// latest resource variable name — "latest" for sdkUpdate
+	latestVarName string,
+	// delta variable name — "delta" for sdkUpdate
+	deltaVarName string,
+	// Number of levels of indentation to use
+	indentLevel int,
+) string {
+	fields := r.CustomSyncFields()
+	if len(fields) == 0 {
+		return ""
+	}
+	indent := strings.Repeat("\t", indentLevel)
+
+	fieldPaths := customSyncFieldPaths(r, fields)
+
+	out := "\n"
+	// The reconciler expects Update to hand back the desired state carrying the
+	// observed status. Build it before syncing so the short-circuit below has
+	// something to return.
+	out += fmt.Sprintf(
+		"%supdatedDesired := %s.DeepCopy()\n", indent, desiredVarName,
+	)
+	out += fmt.Sprintf(
+		"%supdatedDesired.SetStatus(%s)\n", indent, latestVarName,
+	)
+	for i, f := range fields {
+		out += fmt.Sprintf(
+			"%sif %s.DifferentAt(%q) {\n", indent, deltaVarName, fieldPaths[i],
+		)
+		out += fmt.Sprintf(
+			"%s\terr = rm.%s(ctx, %s, %s)\n",
+			indent, f.CustomSyncMethodName(), desiredVarName, latestVarName,
+		)
+		out += fmt.Sprintf("%s\tif err != nil {\n", indent)
+		out += fmt.Sprintf("%s\t\treturn nil, err\n", indent)
+		out += fmt.Sprintf("%s\t}\n", indent)
+		out += fmt.Sprintf("%s}\n", indent)
+	}
+	// Every custom_sync field has now been reconciled through its own API. If
+	// nothing outside that set differs, there is no Update call to make.
+	quoted := make([]string, 0, len(fieldPaths))
+	for _, fp := range fieldPaths {
+		quoted = append(quoted, fmt.Sprintf("%q", fp))
+	}
+	out += fmt.Sprintf(
+		"%sif !%s.DifferentExcept(%s) {\n",
+		indent, deltaVarName, strings.Join(quoted, ", "),
+	)
+	out += fmt.Sprintf(
+		"%s\treturn rm.concreteResource(updatedDesired), nil\n", indent,
+	)
+	out += fmt.Sprintf("%s}\n", indent)
+	return out
+}
+
+// CustomSyncCreate returns Go code that marks the resource unsynced after a
+// successful create when any of its `custom_sync` fields is set.
+//
+// A `custom_sync` field is only ever applied in the update path, so immediately
+// after create the field is present in the resource's Spec but has not been
+// pushed to AWS. Setting the Synced condition to false makes the runtime requeue
+// after requeue.DefaultRequeueAfterDuration (30 seconds), which lands in
+// sdkUpdate and runs the sync. Without this, the resource would report itself
+// synced while the field was still unapplied, and the correction would wait for
+// the full resync period.
+//
+// The Synced condition carries a message so that a user running
+// `kubectl describe` sees why the resource is not synced yet and that the
+// controller intends to sync again on its own.
+//
+// The empty string is returned when the resource has no `custom_sync` fields.
+//
+// Sample output:
+//
+//	if ko.Spec.Tags != nil {
+//	    msg := "Secondary sync required; resource will be requeued"
+//	    ackcondition.SetSynced(&resource{ko}, corev1.ConditionFalse, &msg, nil)
+//	}
+func CustomSyncCreate(
+	r *model.CRD,
+	// the variable name of the resource's Kubernetes object — "ko" for sdkCreate
+	koVarName string,
+	// Number of levels of indentation to use
+	indentLevel int,
+) string {
+	fields := r.CustomSyncFields()
+	if len(fields) == 0 {
+		return ""
+	}
+	indent := strings.Repeat("\t", indentLevel)
+	specPrefix := customSyncSpecPrefix(r)
+
+	// Only mark unsynced when there is actually something to sync. A resource
+	// created without any of these fields set has nothing for the follow-up
+	// reconcile to do.
+	conditions := make([]string, 0, len(fields))
+	for _, f := range fields {
+		conditions = append(conditions, fmt.Sprintf(
+			"%s.%s.%s != nil", koVarName, specPrefix, f.Names.Camel,
+		))
+	}
+
+	out := "\n"
+	out += fmt.Sprintf(
+		"%sif %s {\n", indent, strings.Join(conditions, " || "),
+	)
+	out += fmt.Sprintf("%s\tmsg := %q\n", indent, customSyncPendingMessage)
+	out += fmt.Sprintf(
+		"%s\tackcondition.SetSynced(&resource{%s}, corev1.ConditionFalse, &msg, nil)\n",
+		indent, koVarName,
+	)
+	out += fmt.Sprintf("%s}\n", indent)
+	return out
+}
+
+// customSyncFieldPaths returns the delta field path for each supplied field,
+// e.g. "Spec.Tags". These are the paths that the generated delta.go passes to
+// delta.Add, so they must be constructed the same way — see the fieldPath
+// calculation in CompareResource.
+func customSyncFieldPaths(r *model.CRD, fields []*model.Field) []string {
+	specPrefix := customSyncSpecPrefix(r)
+	paths := make([]string, 0, len(fields))
+	for _, f := range fields {
+		paths = append(paths, fmt.Sprintf("%s.%s", specPrefix, f.Names.Camel))
+	}
+	return paths
+}
+
+// customSyncSpecPrefix returns the Spec prefix without its leading dot, i.e.
+// "Spec" for the default prefix config.
+func customSyncSpecPrefix(r *model.CRD) string {
+	return strings.TrimPrefix(r.Config().PrefixConfig.SpecField, ".")
+}

pkg/generate/code/custom_sync_test.go

@@ -0,0 +1,116 @@
+// Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License"). You may
+// not use this file except in compliance with the License. A copy of the
+// License is located at
+//
+//	 http://aws.amazon.com/apache2.0/
+//
+// or in the "license" file accompanying this file. This file is distributed
+// on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+// express or implied. See the License for the specific language governing
+// permissions and limitations under the License.
+
+package code_test
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/aws-controllers-k8s/code-generator/pkg/generate/code"
+	"github.com/aws-controllers-k8s/code-generator/pkg/testutil"
+)
+
+// TestCustomSyncUpdate verifies the sdkUpdate boilerplate for a resource with
+// two custom_sync fields. Both are collected into a single DifferentExcept
+// call, which is the property that makes generating this worthwhile: a
+// hand-written hook has to be widened by hand every time a field is added, and
+// forgetting to do so silently short-circuits legitimate updates.
+//
+// Each method name is derived from its field name, so the calls are rm.syncTags
+// and rm.syncLogDeliveryConfigurations.
+func TestCustomSyncUpdate(t *testing.T) {
+	assert := assert.New(t)
+	require := require.New(t)
+
+	g := testutil.NewModelForServiceWithOptions(t, "elasticache",
+		&testutil.TestingModelOptions{
+			GeneratorConfigFile: "generator-with-custom-sync.yaml",
+		})
+
+	crd := testutil.GetCRDByName(t, g, "ReplicationGroup")
+	require.NotNil(crd)
+
+	// Fields are emitted in sorted order, so LogDeliveryConfigurations precedes
+	// Tags regardless of the order they appear in generator.yaml.
+	expected := `
+	updatedDesired := desired.DeepCopy()
+	updatedDesired.SetStatus(latest)
+	if delta.DifferentAt("Spec.LogDeliveryConfigurations") {
+		err = rm.syncLogDeliveryConfigurations(ctx, desired, latest)
+		if err != nil {
+			return nil, err
+		}
+	}
+	if delta.DifferentAt("Spec.Tags") {
+		err = rm.syncTags(ctx, desired, latest)
+		if err != nil {
+			return nil, err
+		}
+	}
+	if !delta.DifferentExcept("Spec.LogDeliveryConfigurations", "Spec.Tags") {
+		return rm.concreteResource(updatedDesired), nil
+	}
+`
+	assert.Equal(
+		strings.TrimSpace(expected),
+		strings.TrimSpace(code.CustomSyncUpdate(crd, "desired", "latest", "delta", 1)),
+	)
+}
+
+// TestCustomSyncCreate verifies the post-create marker. The resource is marked
+// unsynced only when at least one custom_sync field is actually set, since a
+// resource created without any of them has nothing for the follow-up reconcile
+// to do. The condition message is generic, so it stays accurate no matter which
+// subset of the fields the user populated.
+func TestCustomSyncCreate(t *testing.T) {
+	assert := assert.New(t)
+	require := require.New(t)
+
+	g := testutil.NewModelForServiceWithOptions(t, "elasticache",
+		&testutil.TestingModelOptions{
+			GeneratorConfigFile: "generator-with-custom-sync.yaml",
+		})
+
+	crd := testutil.GetCRDByName(t, g, "ReplicationGroup")
+	require.NotNil(crd)
+
+	expected := `
+	if ko.Spec.LogDeliveryConfigurations != nil || ko.Spec.Tags != nil {
+		msg := "Secondary sync required; resource will be requeued"
+		ackcondition.SetSynced(&resource{ko}, corev1.ConditionFalse, &msg, nil)
+	}
+`
+	assert.Equal(
+		strings.TrimSpace(expected),
+		strings.TrimSpace(code.CustomSyncCreate(crd, "ko", 1)),
+	)
+}
+
+// TestCustomSyncNoFields confirms both emitters are inert for the overwhelming
+// majority of resources, which have no custom_sync fields at all.
+func TestCustomSyncNoFields(t *testing.T) {
+	assert := assert.New(t)
+	require := require.New(t)
+
+	g := testutil.NewModelForService(t, "elasticache")
+
+	crd := testutil.GetCRDByName(t, g, "ReplicationGroup")
+	require.NotNil(crd)
+
+	assert.Equal("", code.CustomSyncUpdate(crd, "desired", "latest", "delta", 1))
+	assert.Equal("", code.CustomSyncCreate(crd, "ko", 1))
+}