Merge pull request #5194 from camilamacedo86/new-feature-pin-version

✨ (go/v4): Allow informing Go module for external APIs when pinning a downgraded version is required

Author: k8s-ci-robot

docs/book/src/reference/project-config.md

@@ -59,6 +59,14 @@ resources:
     kind: Busybox
     path: sigs.k8s.io/kubebuilder/testdata/project-v4-with-deploy-image/api/v1alpha1
     version: v1alpha1
+  - controller: true
+    domain: io
+    external: true
+    group: cert-manager
+    kind: Certificate
+    path: github.com/cert-manager/cert-manager/pkg/apis/certmanager/v1
+    module: github.com/cert-manager/cert-manager@v1.18.2
+    version: v1
 version: "3"
 ```
 ## Why do we need to store the plugins and data used?
@@ -127,6 +135,14 @@ resources:
     kind: Busybox
     path: sigs.k8s.io/kubebuilder/testdata/project-v4-with-deploy-image/api/v1alpha1
     version: v1alpha1
+  - controller: true
+    domain: io
+    external: true
+    group: cert-manager
+    kind: Certificate
+    path: github.com/cert-manager/cert-manager/pkg/apis/certmanager/v1
+    module: github.com/cert-manager/cert-manager@v1.18.2
+    version: v1
 version: "3"
 ```
 
@@ -152,6 +168,7 @@ Now let's check its layout fields definition:
 | `resources.path`                    | The import path for the API resource. It will be `<repo>/api/<kind>` unless the API added to the project is an external or core-type. For the core-types scenarios, the paths used are mapped [here][core-types]. Or either the path informed by the flag `--external-api-path` |
 | `resources.core`                    | It is `true` when  the group used is from Kubernetes API and the API resource is not defined on the project.                                                                                                                                                                    |
 | `resources.external`                | It is `true` when  the flag `--external-api-path` was used to generated the scaffold for an [External Type][external-type].                                                                                                                                                     |
+| `resources.module`                  | **(Optional)** The Go module path for external API dependencies, optionally including a version (e.g., `github.com/cert-manager/cert-manager@v1.18.2` or just `github.com/cert-manager/cert-manager`). Only used when `external` is `true`. Provided via the `--external-api-module` flag to explicitly pin a specific version in `go.mod` or to specify the module when it cannot be automatically determined from `--external-api-path`. If not provided, `go mod tidy` will resolve the dependency automatically. |
 | `resources.webhooks`                | Store the webhooks data when the sub-command `create webhook` is used.                                                                                                                                                                                                          |
 | `resources.webhooks.spoke`          | Store the API version that will act as the Spoke with the designated Hub version for conversion webhooks.                                                                                                                                                                       |
 | `resources.webhooks.webhookVersion` | The Kubernetes API version (`apiVersion`) used to scaffold the webhook resource.                                                                                                                                                                                                |

docs/book/src/reference/using_an_external_resource.md

@@ -31,6 +31,25 @@ For example, if you're managing Certificates from Cert Manager:
 kubebuilder create api --group certmanager --version v1 --kind Certificate --controller=true --resource=false --external-api-path=github.com/cert-manager/cert-manager/pkg/apis/certmanager/v1 --external-api-domain=io
 ```
 
+<aside class="note">
+<h1>Pinning External API Versions</h1>
+
+You can pin a specific version of the external API dependency using the `--external-api-module` flag:
+
+```shell
+kubebuilder create api --group certmanager --version v1 --kind Certificate \
+  --controller=true --resource=false \
+  --external-api-path=github.com/cert-manager/cert-manager/pkg/apis/certmanager/v1 \
+  --external-api-domain=io \
+  --external-api-module=github.com/cert-manager/cert-manager@v1.18.2
+```
+
+The flag accepts the module path with optional version (e.g., `github.com/cert-manager/cert-manager@v1.18.2`).
+The module is stored in the PROJECT file and added to `go.mod` using `go get`,
+which cleanly adds it as a direct dependency without polluting go.mod with unnecessary indirect dependencies.
+
+</aside>
+
 See the RBAC [markers][markers-rbac] generated for this:
 
 ```go
@@ -75,10 +94,23 @@ definitions since the type is defined in an external project.
 
 ### Creating a Webhook to Manage an External Type
 
-Following an example:
+You can create webhooks for external types by providing the external API path, domain, and optionally the module:
+
+```shell
+kubebuilder create webhook --group certmanager --version v1 --kind Issuer \
+  --defaulting --programmatic-validation \
+  --external-api-path=github.com/cert-manager/cert-manager/pkg/apis/certmanager/v1 \
+  --external-api-domain=cert-manager.io
+```
+
+You can also pin the version using the `--external-api-module` flag:
 
 ```shell
-kubebuilder create webhook --group certmanager --version v1 --kind Issuer --defaulting --programmatic-validation --external-api-path=github.com/cert-manager/cert-manager/pkg/apis/certmanager/v1 --external-api-domain=cert-manager.io
+kubebuilder create webhook --group certmanager --version v1 --kind Issuer \
+  --defaulting --programmatic-validation \
+  --external-api-path=github.com/cert-manager/cert-manager/pkg/apis/certmanager/v1 \
+  --external-api-domain=cert-manager.io \
+  --external-api-module=github.com/cert-manager/cert-manager@v1.18.2
 ```
 
 ## Managing Core Types

pkg/cli/alpha/internal/generate.go

@@ -491,10 +491,14 @@ func createAPI(res resource.Resource) error {
 	args := append([]string{"create", "api"}, getGVKFlags(res)...)
 	args = append(args, getAPIResourceFlags(res)...)
 
-	// Add the external API path flag if the resource is external
+	// Add the external API flags if the resource is external
 	if res.IsExternal() {
 		args = append(args, "--external-api-path", res.Path)
 		args = append(args, "--external-api-domain", res.Domain)
+		// Add module if specified
+		if res.Module != "" {
+			args = append(args, "--external-api-module", res.Module)
+		}
 	}
 
 	if err := util.RunCmd("kubebuilder create api", "kubebuilder", args...); err != nil {
@@ -547,6 +551,10 @@ func getWebhookResourceFlags(res resource.Resource) []string {
 	if res.IsExternal() {
 		args = append(args, "--external-api-path", res.Path)
 		args = append(args, "--external-api-domain", res.Domain)
+		// Add module if specified
+		if res.Module != "" {
+			args = append(args, "--external-api-module", res.Module)
+		}
 	}
 	if res.HasValidationWebhook() {
 		args = append(args, "--programmatic-validation")

pkg/cli/alpha/internal/generate_test.go

@@ -430,6 +430,45 @@ var _ = Describe("generate: get-args-helpers", func() {
 			Expect(flags).To(ContainElements("--external-api-path", "external/test", "--external-api-domain", "test",
 				"--programmatic-validation", "--defaulting", "--conversion", "--spoke", "v2"))
 		})
+
+		It("returns correct flags for external resources with module version", func() {
+			res := resource.Resource{
+				Path:     "github.com/cert-manager/cert-manager/pkg/apis/certmanager/v1",
+				Module:   "github.com/cert-manager/cert-manager@v1.18.2",
+				GVK:      resource.GVK{Group: "cert-manager", Version: "v1", Kind: "Certificate", Domain: "io"},
+				External: true,
+				Webhooks: &resource.Webhooks{
+					Defaulting: true,
+				},
+			}
+			flags := getWebhookResourceFlags(res)
+			Expect(flags).To(ContainElement("--external-api-path"))
+			Expect(flags).To(ContainElement("github.com/cert-manager/cert-manager/pkg/apis/certmanager/v1"))
+			Expect(flags).To(ContainElement("--external-api-domain"))
+			Expect(flags).To(ContainElement("io"))
+			Expect(flags).To(ContainElement("--external-api-module"))
+			Expect(flags).To(ContainElement("github.com/cert-manager/cert-manager@v1.18.2"))
+			Expect(flags).To(ContainElement("--defaulting"))
+		})
+
+		It("returns correct flags for external resources WITHOUT module version", func() {
+			res := resource.Resource{
+				Path:     "github.com/cert-manager/cert-manager/pkg/apis/certmanager/v1",
+				Module:   "", // No module specified
+				GVK:      resource.GVK{Group: "cert-manager", Version: "v1", Kind: "Certificate", Domain: "io"},
+				External: true,
+				Webhooks: &resource.Webhooks{
+					Defaulting: true,
+				},
+			}
+			flags := getWebhookResourceFlags(res)
+			Expect(flags).To(ContainElement("--external-api-path"))
+			Expect(flags).To(ContainElement("github.com/cert-manager/cert-manager/pkg/apis/certmanager/v1"))
+			Expect(flags).To(ContainElement("--external-api-domain"))
+			Expect(flags).To(ContainElement("io"))
+			Expect(flags).NotTo(ContainElement("--external-api-module"))
+			Expect(flags).To(ContainElement("--defaulting"))
+		})
 	})
 })
 
@@ -485,6 +524,34 @@ var _ = Describe("generate: create-helpers", func() {
 				// Run createAPI and verify no errors
 				Expect(createAPI(res)).To(Succeed())
 			})
+
+			It("runs kubebuilder create api successfully with module version", func() {
+				res := resource.Resource{
+					GVK:        resource.GVK{Group: "cert-manager", Version: "v1", Kind: "Certificate", Domain: "io"},
+					Plural:     "certificates",
+					API:        nil, // External resources typically don't scaffold API
+					Controller: true,
+					External:   true,
+					Path:       "github.com/cert-manager/cert-manager/pkg/apis/certmanager/v1",
+					Module:     "github.com/cert-manager/cert-manager@v1.18.2",
+				}
+				// Run createAPI and verify no errors
+				Expect(createAPI(res)).To(Succeed())
+			})
+
+			It("runs kubebuilder create api successfully WITHOUT module version", func() {
+				res := resource.Resource{
+					GVK:        resource.GVK{Group: "cert-manager", Version: "v1", Kind: "Certificate", Domain: "io"},
+					Plural:     "certificates",
+					API:        nil,
+					Controller: true,
+					External:   true,
+					Path:       "github.com/cert-manager/cert-manager/pkg/apis/certmanager/v1",
+					Module:     "", // No module specified
+				}
+				// Run createAPI and verify no errors
+				Expect(createAPI(res)).To(Succeed())
+			})
 		})
 	})
 
@@ -525,6 +592,36 @@ var _ = Describe("generate: create-helpers", func() {
 			// Run createAPIWithDeployImage and verify no errors
 			Expect(createAPIWithDeployImage(resourceData)).To(Succeed())
 		})
+
+		It("validates deploy-image works with external APIs without release version", func() {
+			// This test validates that deploy-image plugin can work with external APIs
+			// even without pinned versions (backward compatibility)
+			resourceData := deployimagev1alpha1.ResourceData{
+				Group:   "cert-manager",
+				Domain:  "io",
+				Version: "v1",
+				Kind:    "Certificate",
+			}
+			resourceData.Options.Image = "busybox:1.36.1"
+			resourceData.Options.RunAsUser = "1001"
+			// Run createAPIWithDeployImage and verify no errors
+			Expect(createAPIWithDeployImage(resourceData)).To(Succeed())
+		})
+
+		It("validates deploy-image can be used alongside external APIs with release version", func() {
+			// This test validates that when external APIs with release versions are used,
+			// deploy-image plugin still works correctly
+			// Note: The release field is stored in the Resource, not in DeployImage's ResourceData
+			resourceData := deployimagev1alpha1.ResourceData{
+				Group:   "example.com",
+				Version: "v1",
+				Kind:    "Memcached",
+			}
+			resourceData.Options.Image = "memcached:1.6.26"
+			resourceData.Options.ContainerPort = "11211"
+			// Run createAPIWithDeployImage and verify no errors
+			Expect(createAPIWithDeployImage(resourceData)).To(Succeed())
+		})
 	})
 })
 

pkg/model/resource/resource.go

@@ -46,6 +46,11 @@ type Resource struct {
 	// External specifies if the resource is defined externally.
 	External bool `json:"external,omitempty"`
 
+	// Module specifies the Go module path for external API dependencies.
+	// Can optionally include @version to pin the dependency (e.g., "github.com/org/repo@v1.2.3").
+	// This is only used when External is true.
+	Module string `json:"module,omitempty"`
+
 	// Core specifies if the resource is from Kubernetes API.
 	Core bool `json:"core,omitempty"`
 }

pkg/plugins/golang/options.go

@@ -57,10 +57,14 @@ type Options struct {
 	// ExternalAPIPath allows to inform a path for APIs not defined in the project
 	ExternalAPIPath string
 
-	// ExternalAPIPath allows to inform the resource domain to build the Qualified Group
+	// ExternalAPIDomain allows to inform the resource domain to build the Qualified Group
 	// to generate the RBAC markers
 	ExternalAPIDomain string
 
+	// ExternalAPIModule specifies the Go module path for the external API with optional version.
+	// Example: github.com/cert-manager/cert-manager@v1.18.2
+	ExternalAPIModule string
+
 	// Namespaced is true if the resource should be namespaced.
 	Namespaced bool
 
@@ -124,6 +128,14 @@ func (opts Options) UpdateResource(res *resource.Resource, c config.Config) {
 
 	if len(opts.ExternalAPIPath) > 0 {
 		res.External = true
+		res.Path = opts.ExternalAPIPath
+		if len(opts.ExternalAPIDomain) > 0 {
+			res.Domain = opts.ExternalAPIDomain
+		}
+		// Store module path if provided
+		if len(opts.ExternalAPIModule) > 0 {
+			res.Module = opts.ExternalAPIModule
+		}
 	}
 
 	// domain and path may need to be changed in case we are referring to a builtin core resource:

pkg/plugins/golang/v4/api.go

@@ -116,6 +116,9 @@ func (p *createAPISubcommand) BindFlags(fs *pflag.FlagSet) {
 	fs.StringVar(&p.options.ExternalAPIDomain, "external-api-domain", "",
 		"Specify the domain name for the external API. This domain is used to generate accurate RBAC "+
 			"markers and permissions for the external resources (e.g., cert-manager.io).")
+
+	fs.StringVar(&p.options.ExternalAPIModule, "external-api-module", "",
+		"external API module with optional version (e.g., github.com/cert-manager/cert-manager@v1.18.2)")
 }
 
 func (p *createAPISubcommand) InjectConfig(c config.Config) error {
@@ -138,13 +141,19 @@ func (p *createAPISubcommand) InjectResource(res *resource.Resource) error {
 
 	// Ensure that external API options cannot be used when creating an API in the project.
 	if p.options.DoAPI {
-		if len(p.options.ExternalAPIPath) != 0 || len(p.options.ExternalAPIDomain) != 0 {
-			return errors.New("cannot use '--external-api-path' or '--external-api-domain' " +
+		if len(p.options.ExternalAPIPath) != 0 || len(p.options.ExternalAPIDomain) != 0 ||
+			len(p.options.ExternalAPIModule) != 0 {
+			return errors.New("cannot use '--external-api-path', '--external-api-domain', or '--external-api-module' " +
 				"when creating an API in the project with '--resource=true'. " +
 				"Use '--resource=false' when referencing an external API")
 		}
 	}
 
+	// Validate that --external-api-module requires --external-api-path
+	if len(p.options.ExternalAPIModule) != 0 && len(p.options.ExternalAPIPath) == 0 {
+		return errors.New("'--external-api-module' requires '--external-api-path' to be specified")
+	}
+
 	p.options.UpdateResource(p.resource, p.config)
 
 	if err := p.resource.Validate(); err != nil {
@@ -188,6 +197,16 @@ func (p *createAPISubcommand) Scaffold(fs machinery.Filesystem) error {
 }
 
 func (p *createAPISubcommand) PostScaffold() error {
+	// If external API with module specified, add it using go get
+	if p.resource.IsExternal() && p.resource.Module != "" {
+		log.Info("Adding external API dependency", "module", p.resource.Module)
+		// Use go get to add the dependency cleanly as a direct requirement
+		err := util.RunCmd("Add external API dependency", "go", "get", p.resource.Module)
+		if err != nil {
+			return fmt.Errorf("error adding external API dependency: %w", err)
+		}
+	}
+
 	err := util.RunCmd("Update dependencies", "go", "mod", "tidy")
 	if err != nil {
 		return fmt.Errorf("error updating go dependencies: %w", err)

pkg/plugins/golang/v4/webhook.go

@@ -19,6 +19,7 @@ package v4
 import (
 	"errors"
 	"fmt"
+	log "log/slog"
 	"strings"
 
 	"github.com/spf13/pflag"
@@ -115,13 +116,16 @@ func (p *createWebhookSubcommand) BindFlags(fs *pflag.FlagSet) {
 			"This option will be removed in future versions.")
 
 	fs.StringVar(&p.options.ExternalAPIPath, "external-api-path", "",
-		"Specify the Go package import path for the external API. This is used to scaffold controllers for resources "+
+		"Specify the Go package import path for the external API. This is used to scaffold webhooks for resources "+
 			"defined outside this project (e.g., github.com/cert-manager/cert-manager/pkg/apis/certmanager/v1).")
 
 	fs.StringVar(&p.options.ExternalAPIDomain, "external-api-domain", "",
 		"Specify the domain name for the external API. This domain is used to generate accurate RBAC "+
 			"markers and permissions for the external resources (e.g., cert-manager.io).")
 
+	fs.StringVar(&p.options.ExternalAPIModule, "external-api-module", "",
+		"external API module with optional version (e.g., github.com/cert-manager/cert-manager@v1.18.2)")
+
 	fs.BoolVar(&p.force, "force", false,
 		"attempt to create resource even if it already exists")
 }
@@ -154,6 +158,11 @@ func (p *createWebhookSubcommand) InjectResource(res *resource.Resource) error {
 		return fmt.Errorf("--validation-path can only be used with --programmatic-validation")
 	}
 
+	// Validate that --external-api-module requires --external-api-path
+	if len(p.options.ExternalAPIModule) != 0 && len(p.options.ExternalAPIPath) == 0 {
+		return errors.New("'--external-api-module' requires '--external-api-path' to be specified")
+	}
+
 	p.options.UpdateResource(p.resource, p.config)
 
 	if err := p.resource.Validate(); err != nil {
@@ -193,6 +202,16 @@ func (p *createWebhookSubcommand) Scaffold(fs machinery.Filesystem) error {
 }
 
 func (p *createWebhookSubcommand) PostScaffold() error {
+	// If external API with module specified, add it using go get
+	if p.resource.IsExternal() && p.resource.Module != "" {
+		log.Info("Adding external API dependency", "module", p.resource.Module)
+		// Use go get to add the dependency cleanly as a direct requirement
+		err := pluginutil.RunCmd("Add external API dependency", "go", "get", p.resource.Module)
+		if err != nil {
+			return fmt.Errorf("error adding external API dependency: %w", err)
+		}
+	}
+
 	err := pluginutil.RunCmd("Update dependencies", "go", "mod", "tidy")
 	if err != nil {
 		return fmt.Errorf("error updating go dependencies: %w", err)

test/e2e/alphagenerate/generate_v4_test.go

@@ -170,6 +170,8 @@ func validateV4ProjectFile(kbc *utils.TestContext, projectFile string) {
 	Expect(certmanagerResource.Webhooks).To(BeNil(), "Certificate API should not have webhooks")
 	Expect(certmanagerResource.Path).To(Equal("github.com/cert-manager/cert-manager/pkg/apis/certmanager/v1"),
 		"Certificate API should have expected path")
+	Expect(certmanagerResource.Module).To(Equal("github.com/cert-manager/cert-manager@v1.18.2"),
+		"Certificate API should have module with version v1.18.2 stored in PROJECT file")
 
 	By("validating the External API with kind Issuer from certManager")
 	issuerGVK := resource.GVK{
@@ -187,6 +189,8 @@ func validateV4ProjectFile(kbc *utils.TestContext, projectFile string) {
 	Expect(issuerResource.API).To(BeNil(), "Issuer API should not have API scaffold")
 	Expect(issuerResource.Path).To(Equal("github.com/cert-manager/cert-manager/pkg/apis/certmanager/v1"),
 		"Issuer API should have expected path")
+	Expect(issuerResource.Module).To(Equal("github.com/cert-manager/cert-manager@v1.18.2"),
+		"Issuer API should have module with version v1.18.2 stored in PROJECT file")
 
 	By("validating the Webhook for Issuer API")
 	Expect(admiralResource.Webhooks.Defaulting).To(BeTrue(), "Issuer API should have a defaulting webhook")