Merge pull request #5161 from kubernetes-sigs/copilot/add-plugins-api-support

✨ (External Plugins API) Add PluginChain field to external plugin API

Author: k8s-ci-robot

docs/book/src/plugins/extending/external-plugins.md

@@ -30,17 +30,25 @@ structures.
 
 `PluginRequest` contains the data collected from the CLI and any previously executed plugins. Kubebuilder sends this data as a JSON object to the external plugin via `stdin`.
 
-**Example `PluginRequest` (triggered by `kubebuilder init --plugins sampleexternalplugin/v1 --domain my.domain`):**
+**Example `PluginRequest` (triggered by `kubebuilder init --plugins go/v4,sampleexternalplugin/v1 --domain my.domain`):**
 
 ```json
 {
   "apiVersion": "v1alpha1",
   "args": ["--domain", "my.domain"],
   "command": "init",
-  "universe": {}
+  "universe": {},
+  "pluginChain": ["go.kubebuilder.io/v4", "kustomize.common.kubebuilder.io/v2", "sampleexternalplugin/v1"]
 }
 ```
 
+**Fields:**
+- `apiVersion`: Version of the PluginRequest schema.
+- `args`: Command-line arguments passed to the plugin.
+- `command`: The subcommand being executed (e.g., `init`, `create api`, `create webhook`, `edit`).
+- `universe`: Map of file paths to contents, updated across the plugin chain.
+- `pluginChain` (optional): Array of plugin keys in the chain. This allows external plugins to determine which other plugins are being used. For example, a plugin can check if `go.kubebuilder.io/v4` or `go.kubebuilder.io/v3` is in the chain to adjust its scaffolding accordingly.
+
 ### PluginResponse
 
 `PluginResponse` contains the modifications made by the plugin to the project. This data is serialized as JSON and returned to Kubebuilder through `stdout`.

pkg/plugin/external/types.go

@@ -35,6 +35,11 @@ type PluginRequest struct {
 	// Universe represents the modified file contents that gets updated over a series of plugin runs
 	// across the plugin chain. Initially, it starts out as empty.
 	Universe map[string]string `json:"universe"`
+
+	// PluginChain contains the full plugin chain being used for this project.
+	// This allows external plugins to know which other plugins are in use.
+	// Format: ["go.kubebuilder.io/v4", "kustomize.common.kubebuilder.io/v2"]
+	PluginChain []string `json:"pluginChain,omitempty"`
 }
 
 // PluginResponse is returned to kubebuilder by the plugin and contains all files

pkg/plugins/external/api.go

@@ -19,6 +19,7 @@ package external
 import (
 	"github.com/spf13/pflag"
 
+	"sigs.k8s.io/kubebuilder/v4/pkg/config"
 	"sigs.k8s.io/kubebuilder/v4/pkg/machinery"
 	"sigs.k8s.io/kubebuilder/v4/pkg/model/resource"
 	"sigs.k8s.io/kubebuilder/v4/pkg/plugin"
@@ -32,8 +33,15 @@ const (
 )
 
 type createAPISubcommand struct {
-	Path string
-	Args []string
+	Path        string
+	Args        []string
+	pluginChain []string
+}
+
+// InjectConfig injects the project configuration to access plugin chain information
+func (p *createAPISubcommand) InjectConfig(c config.Config) error {
+	p.pluginChain = c.GetPluginChain()
+	return nil
 }
 
 func (p *createAPISubcommand) InjectResource(*resource.Resource) error {
@@ -51,9 +59,10 @@ func (p *createAPISubcommand) BindFlags(fs *pflag.FlagSet) {
 
 func (p *createAPISubcommand) Scaffold(fs machinery.Filesystem) error {
 	req := external.PluginRequest{
-		APIVersion: defaultAPIVersion,
-		Command:    "create api",
-		Args:       p.Args,
+		APIVersion:  defaultAPIVersion,
+		Command:     "create api",
+		Args:        p.Args,
+		PluginChain: p.pluginChain,
 	}
 
 	err := handlePluginResponse(fs, req, p.Path)

pkg/plugins/external/edit.go

@@ -19,6 +19,7 @@ package external
 import (
 	"github.com/spf13/pflag"
 
+	"sigs.k8s.io/kubebuilder/v4/pkg/config"
 	"sigs.k8s.io/kubebuilder/v4/pkg/machinery"
 	"sigs.k8s.io/kubebuilder/v4/pkg/plugin"
 	"sigs.k8s.io/kubebuilder/v4/pkg/plugin/external"
@@ -27,8 +28,15 @@ import (
 var _ plugin.EditSubcommand = &editSubcommand{}
 
 type editSubcommand struct {
-	Path string
-	Args []string
+	Path        string
+	Args        []string
+	pluginChain []string
+}
+
+// InjectConfig injects the project configuration to access plugin chain information
+func (p *editSubcommand) InjectConfig(c config.Config) error {
+	p.pluginChain = c.GetPluginChain()
+	return nil
 }
 
 func (p *editSubcommand) UpdateMetadata(_ plugin.CLIMetadata, subcmdMeta *plugin.SubcommandMetadata) {
@@ -41,9 +49,10 @@ func (p *editSubcommand) BindFlags(fs *pflag.FlagSet) {
 
 func (p *editSubcommand) Scaffold(fs machinery.Filesystem) error {
 	req := external.PluginRequest{
-		APIVersion: defaultAPIVersion,
-		Command:    "edit",
-		Args:       p.Args,
+		APIVersion:  defaultAPIVersion,
+		Command:     "edit",
+		Args:        p.Args,
+		PluginChain: p.pluginChain,
 	}
 
 	err := handlePluginResponse(fs, req, p.Path)

pkg/plugins/external/external_test.go

@@ -59,6 +59,31 @@ func (m *mockInValidOutputGetter) GetExecOutput(_ []byte, _ string) ([]byte, err
 	return nil, fmt.Errorf("error getting exec command output")
 }
 
+type mockPluginChainCaptureGetter struct {
+	capturedChain *[]string
+}
+
+var _ ExecOutputGetter = &mockPluginChainCaptureGetter{}
+
+func (m *mockPluginChainCaptureGetter) GetExecOutput(request []byte, _ string) ([]byte, error) {
+	// Parse the request to capture the plugin chain
+	var req external.PluginRequest
+	if err := json.Unmarshal(request, &req); err != nil {
+		return nil, fmt.Errorf("error unmarshalling request: %w", err)
+	}
+
+	// Capture the plugin chain
+	*m.capturedChain = req.PluginChain
+
+	// Return a valid response
+	return []byte(`{
+		"command": "init",
+		"error": false,
+		"error_msg": "none",
+		"universe": {"LICENSE": "Apache 2.0 License\n"}
+	}`), nil
+}
+
 type mockValidOsWdGetter struct{}
 
 var _ OsWdGetter = &mockValidOsWdGetter{}
@@ -754,6 +779,85 @@ var _ = Describe("Run external plugin using Scaffold", func() {
 			}
 		})
 	})
+
+	Context("PluginChain is passed to external plugin", func() {
+		var (
+			pluginChainCaptured []string
+			mockOutputGetter    *mockPluginChainCaptureGetter
+		)
+
+		BeforeEach(func() {
+			mockOutputGetter = &mockPluginChainCaptureGetter{
+				capturedChain: &pluginChainCaptured,
+			}
+			outputGetter = mockOutputGetter
+			currentDirGetter = &mockValidOsWdGetter{}
+		})
+
+		It("should pass plugin chain to init subcommand", func() {
+			fs := machinery.Filesystem{
+				FS: afero.NewMemMapFs(),
+			}
+
+			i := initSubcommand{
+				Path:        "test.sh",
+				Args:        []string{"--domain", "example.com"},
+				pluginChain: []string{"go.kubebuilder.io/v4", "kustomize.common.kubebuilder.io/v2"},
+			}
+
+			err := i.Scaffold(fs)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(pluginChainCaptured).To(Equal([]string{"go.kubebuilder.io/v4", "kustomize.common.kubebuilder.io/v2"}))
+		})
+
+		It("should pass plugin chain to create api subcommand", func() {
+			fs := machinery.Filesystem{
+				FS: afero.NewMemMapFs(),
+			}
+
+			c := createAPISubcommand{
+				Path:        "test.sh",
+				Args:        []string{"--group", "apps", "--version", "v1", "--kind", "MyKind"},
+				pluginChain: []string{"go.kubebuilder.io/v4"},
+			}
+
+			err := c.Scaffold(fs)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(pluginChainCaptured).To(Equal([]string{"go.kubebuilder.io/v4"}))
+		})
+
+		It("should pass plugin chain to create webhook subcommand", func() {
+			fs := machinery.Filesystem{
+				FS: afero.NewMemMapFs(),
+			}
+
+			w := createWebhookSubcommand{
+				Path:        "test.sh",
+				Args:        []string{"--group", "apps", "--version", "v1", "--kind", "MyKind"},
+				pluginChain: []string{"go.kubebuilder.io/v3"},
+			}
+
+			err := w.Scaffold(fs)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(pluginChainCaptured).To(Equal([]string{"go.kubebuilder.io/v3"}))
+		})
+
+		It("should pass plugin chain to edit subcommand", func() {
+			fs := machinery.Filesystem{
+				FS: afero.NewMemMapFs(),
+			}
+
+			e := editSubcommand{
+				Path:        "test.sh",
+				Args:        []string{"--multigroup"},
+				pluginChain: []string{"go.kubebuilder.io/v4", "declarative.go.kubebuilder.io/v1"},
+			}
+
+			err := e.Scaffold(fs)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(pluginChainCaptured).To(Equal([]string{"go.kubebuilder.io/v4", "declarative.go.kubebuilder.io/v1"}))
+		})
+	})
 })
 
 func getFlags() []external.Flag {

pkg/plugins/external/init.go

@@ -19,6 +19,7 @@ package external
 import (
 	"github.com/spf13/pflag"
 
+	"sigs.k8s.io/kubebuilder/v4/pkg/config"
 	"sigs.k8s.io/kubebuilder/v4/pkg/machinery"
 	"sigs.k8s.io/kubebuilder/v4/pkg/plugin"
 	"sigs.k8s.io/kubebuilder/v4/pkg/plugin/external"
@@ -27,8 +28,15 @@ import (
 var _ plugin.InitSubcommand = &initSubcommand{}
 
 type initSubcommand struct {
-	Path string
-	Args []string
+	Path        string
+	Args        []string
+	pluginChain []string
+}
+
+// InjectConfig injects the project configuration to access plugin chain information
+func (p *initSubcommand) InjectConfig(c config.Config) error {
+	p.pluginChain = c.GetPluginChain()
+	return nil
 }
 
 func (p *initSubcommand) UpdateMetadata(_ plugin.CLIMetadata, subcmdMeta *plugin.SubcommandMetadata) {
@@ -41,9 +49,10 @@ func (p *initSubcommand) BindFlags(fs *pflag.FlagSet) {
 
 func (p *initSubcommand) Scaffold(fs machinery.Filesystem) error {
 	req := external.PluginRequest{
-		APIVersion: defaultAPIVersion,
-		Command:    "init",
-		Args:       p.Args,
+		APIVersion:  defaultAPIVersion,
+		Command:     "init",
+		Args:        p.Args,
+		PluginChain: p.pluginChain,
 	}
 
 	err := handlePluginResponse(fs, req, p.Path)

pkg/plugins/external/webhook.go

@@ -19,6 +19,7 @@ package external
 import (
 	"github.com/spf13/pflag"
 
+	"sigs.k8s.io/kubebuilder/v4/pkg/config"
 	"sigs.k8s.io/kubebuilder/v4/pkg/machinery"
 	"sigs.k8s.io/kubebuilder/v4/pkg/model/resource"
 	"sigs.k8s.io/kubebuilder/v4/pkg/plugin"
@@ -28,8 +29,15 @@ import (
 var _ plugin.CreateWebhookSubcommand = &createWebhookSubcommand{}
 
 type createWebhookSubcommand struct {
-	Path string
-	Args []string
+	Path        string
+	Args        []string
+	pluginChain []string
+}
+
+// InjectConfig injects the project configuration to access plugin chain information
+func (p *createWebhookSubcommand) InjectConfig(c config.Config) error {
+	p.pluginChain = c.GetPluginChain()
+	return nil
 }
 
 func (p *createWebhookSubcommand) InjectResource(*resource.Resource) error {
@@ -47,9 +55,10 @@ func (p *createWebhookSubcommand) BindFlags(fs *pflag.FlagSet) {
 
 func (p *createWebhookSubcommand) Scaffold(fs machinery.Filesystem) error {
 	req := external.PluginRequest{
-		APIVersion: defaultAPIVersion,
-		Command:    "create webhook",
-		Args:       p.Args,
+		APIVersion:  defaultAPIVersion,
+		Command:     "create webhook",
+		Args:        p.Args,
+		PluginChain: p.pluginChain,
 	}
 
 	err := handlePluginResponse(fs, req, p.Path)