✨ Add support for external ApplyConfiguration mappings (#1327)

* Add support for external apply configurations

* Generate help for external AC marker

Using:

```
go generate ./cmd/controller-gen/...
```

* Add `testdata/external` and `testdata/externalac`

Add packages under `testdata` that define an external type to be used
for testing applyconfiguration generation for types that reference
external types.

* Add `EmbeddedExternalSpec` to `cronjob_types.go`

This type is used to test generation of ACs for types that embed
external types.

* Update `testdata` with generated ACs

Run the tests with `UPDATE=1` to regenerate the testdata files.

* Update existing AC generator tests

Pass the `externalApplyConfigurations` option to the
`applyconfiguration` generator in the other tests so that they correctly
generate `ApplyConfiguration` types now that an external type is used in
the `CronJob`.

Author: andrew-farries

pkg/applyconfiguration/applyconfiguration_integration_test.go

@@ -109,7 +109,7 @@ var _ = Describe("ApplyConfiguration generation from API types", func() {
 		Expect(optionsRegistry.Register(markers.Must(markers.MakeDefinition("applyconfiguration", markers.DescribesPackage, Generator{})))).To(Succeed())
 
 		rt, err := genall.FromOptions(optionsRegistry, []string{
-			"applyconfiguration",
+			"applyconfiguration:externalApplyConfigurations=sigs.k8s.io/controller-tools/pkg/applyconfiguration/testdata/cronjob/external.ExternalData@sigs.k8s.io/controller-tools/pkg/applyconfiguration/testdata/cronjob/externalac",
 			"paths=./api/v1",
 		})
 		Expect(err).NotTo(HaveOccurred())
@@ -218,7 +218,7 @@ var _ = Describe("ApplyConfiguration generation from API types", func() {
 
 		rt, err := genall.FromOptions(optionsRegistry, []string{
 			"crd:allowDangerousTypes=true,ignoreUnexportedFields=true", // Run another generator first to make sure they don't interfere; see also: the comment on cronjob_types.go:UntypedBlob
-			"applyconfiguration",
+			"applyconfiguration:externalApplyConfigurations=sigs.k8s.io/controller-tools/pkg/applyconfiguration/testdata/cronjob/external.ExternalData@sigs.k8s.io/controller-tools/pkg/applyconfiguration/testdata/cronjob/externalac",
 			"paths=./api/v1",
 		})
 		Expect(err).NotTo(HaveOccurred())

pkg/applyconfiguration/gen.go

@@ -20,8 +20,12 @@ import (
 	"errors"
 	"fmt"
 	"go/ast"
+	"maps"
 	"os"
 	"path/filepath"
+	"strings"
+
+	"k8s.io/gengo/v2/types"
 
 	"k8s.io/apimachinery/pkg/util/sets"
 	"k8s.io/code-generator/cmd/applyconfiguration-gen/args"
@@ -56,6 +60,16 @@ const defaultOutputPackage = "applyconfiguration"
 type Generator struct {
 	// HeaderFile specifies the header text (e.g. license) to prepend to generated files.
 	HeaderFile string `marker:",optional"`
+
+	// ExternalApplyConfigurations provides mappings between external types and their applyconfiguration packages.
+	//
+	// Use this to reference apply configuration types for external types referenced
+	// by the Go structs provided as input. Each entry should be in the format:
+	//   <package>.<TypeName>@<applyconfiguration-package>
+	//
+	// For example, to reference the apply configuration for corev1.LocalObjectReference:
+	//   k8s.io/api/core/v1.LocalObjectReference@k8s.io/client-go/applyconfigurations/core/v1
+	ExternalApplyConfigurations []string `marker:",optional"`
 }
 
 func (Generator) CheckFilter() loader.NodeFilter {
@@ -143,10 +157,22 @@ func (d Generator) Generate(ctx *genall.GenerationContext) error {
 		headerFilePath = tmpFile.Name()
 	}
 
+	// Parse external apply configurations
+	externalACs := make(map[types.Name]string)
+	for _, ext := range d.ExternalApplyConfigurations {
+		parts := strings.SplitN(ext, "@", 2)
+		if len(parts) != 2 {
+			return fmt.Errorf("invalid external apply configuration format %q, expected <package>.<TypeName>@<applyconfiguration-package>", ext)
+		}
+		typeName := types.ParseFullyQualifiedName(parts[0])
+		externalACs[typeName] = parts[1]
+	}
+
 	objGenCtx := ObjectGenCtx{
-		Collector:      ctx.Collector,
-		Checker:        ctx.Checker,
-		HeaderFilePath: headerFilePath,
+		Collector:                   ctx.Collector,
+		Checker:                     ctx.Checker,
+		HeaderFilePath:              headerFilePath,
+		ExternalApplyConfigurations: externalACs,
 	}
 
 	errs := []error{}
@@ -167,9 +193,10 @@ func (d Generator) Generate(ctx *genall.GenerationContext) error {
 // It mostly exists so that generating for a package can be easily tested without
 // requiring a full set of output rules, etc.
 type ObjectGenCtx struct {
-	Collector      *markers.Collector
-	Checker        *loader.TypeChecker
-	HeaderFilePath string
+	Collector                   *markers.Collector
+	Checker                     *loader.TypeChecker
+	HeaderFilePath              string
+	ExternalApplyConfigurations map[types.Name]string
 }
 
 // generateForPackage generates apply configuration implementations for
@@ -186,6 +213,9 @@ func (ctx *ObjectGenCtx) generateForPackage(root *loader.Package) error {
 	arguments := args.New()
 	arguments.GoHeaderFile = ctx.HeaderFilePath
 
+	// Set external apply configurations
+	maps.Copy(arguments.ExternalApplyConfigurations, ctx.ExternalApplyConfigurations)
+
 	outpkg := outputPkg(ctx.Collector, root)
 
 	arguments.OutputDir = filepath.Join(root.Dir, outpkg)

pkg/applyconfiguration/testdata/cronjob/api/v1/applyconfiguration/api/v1/cronjobspec.go

@@ -36,6 +36,8 @@ import (
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 	"k8s.io/apimachinery/pkg/runtime"
 	"k8s.io/apimachinery/pkg/util/intstr"
+
+	"sigs.k8s.io/controller-tools/pkg/applyconfiguration/testdata/cronjob/external"
 )
 
 // EDIT THIS FILE!  THIS IS SCAFFOLDING FOR YOU TO OWN!
@@ -390,6 +392,10 @@ type CronJobSpec struct {
 	// Test that we can add a field that can only be set to a non-default value on updates using XValidation OptionalOldSelf.
 	// +kubebuilder:validation:XValidation:rule="oldSelf.hasValue() || self == 0",message="must be set to 0 on creation. can be set to any value on an update.",optionalOldSelf=true
 	OnlyAllowSettingOnUpdate int32 `json:"onlyAllowSettingOnUpdate,omitempty"`
+
+	// EmbeddedExternal tests the ExternalApplyConfigurations feature.
+	// +optional
+	EmbeddedExternal *EmbeddedExternalSpec `json:"embeddedExternal,omitempty"`
 }
 
 type InlineAlias = EmbeddedStruct
@@ -766,3 +772,12 @@ type CronJobList struct {
 	metav1.ListMeta `json:"metadata,omitempty"`
 	Items           []CronJob `json:"items"`
 }
+
+// EmbeddedExternalSpec embeds an external type with json:",inline".
+// Used to test the ExternalApplyConfigurations feature.
+type EmbeddedExternalSpec struct {
+	external.ExternalData `json:",inline"`
+
+	// Extra is an additional field.
+	Extra string `json:"extra,omitempty"`
+}

pkg/applyconfiguration/testdata/cronjob/api/v1/applyconfiguration/api/v1/embeddedexternalspec.go

@@ -0,0 +1,25 @@
+/*
+Copyright 2024 The Kubernetes Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License 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 external
+
+// ExternalData is a type defined outside the API package,
+// used to test generation of apply configurations for types
+// that reference external types.
+type ExternalData struct {
+	Key   string `json:"key,omitempty"`
+	Value string `json:"value,omitempty"`
+}

pkg/applyconfiguration/testdata/cronjob/api/v1/applyconfiguration/utils.go

@@ -0,0 +1,24 @@
+/*
+Copyright 2024 The Kubernetes Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License 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 externalac
+
+// ExternalDataApplyConfiguration is a placeholder AC type for testing.
+// In real usage, this would be a generated apply configuration type.
+type ExternalDataApplyConfiguration struct {
+	Key   *string `json:"key,omitempty"`
+	Value *string `json:"value,omitempty"`
+}