Refactor sampleexternalplugin to be a Valid Reference Implementation

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

@@ -30,13 +30,13 @@ 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 edit --plugins sampleexternalplugin/v1`):**
 
 ```json
 {
   "apiVersion": "v1alpha1",
-  "args": ["--domain", "my.domain"],
-  "command": "init",
+  "args": [],
+  "command": "edit",
   "universe": {}
 }
 ```
@@ -49,13 +49,14 @@ structures.
 ```json
 {
   "apiVersion": "v1alpha1",
-  "command": "init",
+  "command": "edit",
   "metadata": {
-    "description": "The `init` subcommand initializes a project via Kubebuilder. It scaffolds a single file: `initFile`.",
-    "examples": "kubebuilder init --plugins sampleexternalplugin/v1 --domain my.domain"
+    "description": "The `edit` subcommand adds Prometheus ServiceMonitor configuration for monitoring your operator.",
+    "examples": "kubebuilder edit --plugins sampleexternalplugin/v1"
   },
   "universe": {
-    "initFile": "A file created with the `init` subcommand."
+    "config/prometheus/monitor.yaml": "# Prometheus ServiceMonitor manifest...",
+    "config/prometheus/kustomization.yaml": "resources:\n  - monitor.yaml\n"
   },
   "error": false,
   "errorMsgs": []
@@ -120,26 +121,15 @@ Otherwise, Kubebuilder would search for the plugins in a default path based on y
 You can now use it by calling the CLI commands:
 
 ```sh
-# Initialize a new project with the external plugin named `sampleplugin`
-kubebuilder init --plugins sampleplugin/v1
+# Update the project configuration with the sample external plugin
+# The sampleexternalplugin adds Prometheus ServiceMonitor configuration
+kubebuilder edit --plugins sampleexternalplugin/v1
 
-# Display help information of the `init` subcommand of the external plugin
-kubebuilder init --plugins sampleplugin/v1 --help
+# Display help information for the edit subcommand
+kubebuilder edit --plugins sampleexternalplugin/v1 --help
 
-# Create a new API with the above external plugin with a customized flag `number`
-kubebuilder create api --plugins sampleplugin/v1 --number 2
-
-# Create a webhook with the above external plugin with a customized flag `hooked`
-kubebuilder create webhook --plugins sampleplugin/v1 --hooked
-
-# Update the project configuration with the above external plugin
-kubebuilder edit --plugins sampleplugin/v1
-
-# Create new APIs with external plugins v1 and v2 by respecting the plugin chaining order
-kubebuilder create api --plugins sampleplugin/v1,sampleplugin/v2
-
-# Create new APIs with the go/v4 plugin and then pass those files to the external plugin by respecting the plugin chaining order
-kubebuilder create api --plugins go/v4,sampleplugin/v1
+# Plugin chaining example: Use go/v4 plugin first, then apply external plugin
+kubebuilder edit --plugins go/v4,sampleexternalplugin/v1
 ```
 
 ## Further resources

docs/book/src/simple-external-plugin-tutorial/testdata/sampleexternalplugin/v1/cmd/cmd.go

@@ -59,19 +59,10 @@ func Run() {
 
 	// Run logic depending on the command that is requested by Kubebuilder
 	switch pluginRequest.Command {
-	// the `init` subcommand is often used when initializing a new project
-	case "init":
-		response = scaffolds.InitCmd(pluginRequest)
-	// the `create api` subcommand is often used after initializing a project
-	// with the `init` subcommand to create a controller and CRDs for a
-	// provided group, version, and kind
-	case "create api":
-		response = scaffolds.ApiCmd(pluginRequest)
-	// the `create webhook` subcommand is often used after initializing a project
-	// with the `init` subcommand to create a webhook for a provided
-	// group, version, and kind
-	case "create webhook":
-		response = scaffolds.WebhookCmd(pluginRequest)
+	// the `edit` subcommand is used to add optional features to an existing project
+	// This is a realistic use case for external plugins - adding optional monitoring
+	case "edit":
+		response = scaffolds.EditCmd(pluginRequest)
 	// the `flags` subcommand is used to customize the flags that
 	// the Kubebuilder cli will bind for use with this plugin
 	case "flags":

docs/book/src/simple-external-plugin-tutorial/testdata/sampleexternalplugin/v1/cmd/flags.go

@@ -37,12 +37,8 @@ func flagsCmd(pr *external.PluginRequest) external.PluginResponse {
 	}
 
 	switch pr.Command {
-	case "init":
-		pluginResponse.Flags = scaffolds.InitFlags
-	case "create api":
-		pluginResponse.Flags = scaffolds.ApiFlags
-	case "create webhook":
-		pluginResponse.Flags = scaffolds.WebhookFlags
+	case "edit":
+		pluginResponse.Flags = scaffolds.EditFlags
 	default:
 		pluginResponse.Error = true
 		pluginResponse.ErrorMsgs = []string{

docs/book/src/simple-external-plugin-tutorial/testdata/sampleexternalplugin/v1/cmd/metadata.go

@@ -39,9 +39,7 @@ func metadataCmd(pr *external.PluginRequest) external.PluginResponse {
 
 	// Here is an example of parsing multiple flags from a Kubebuilder external plugin request
 	flagsToParse := pflag.NewFlagSet("flagsFlags", pflag.ContinueOnError)
-	flagsToParse.Bool("init", false, "sets the init flag to true")
-	flagsToParse.Bool("api", false, "sets the api flag to true")
-	flagsToParse.Bool("webhook", false, "sets the webhook flag to true")
+	flagsToParse.Bool("edit", false, "sets the edit flag to true")
 
 	if err := flagsToParse.Parse(pr.Args); err != nil {
 		pluginResponse.Error = true
@@ -51,22 +49,14 @@ func metadataCmd(pr *external.PluginRequest) external.PluginResponse {
 		return pluginResponse
 	}
 
-	initFlag, _ := flagsToParse.GetBool("init")
-	apiFlag, _ := flagsToParse.GetBool("api")
-	webhookFlag, _ := flagsToParse.GetBool("webhook")
+	editFlag, _ := flagsToParse.GetBool("edit")
 
 	// The Phase 2 Plugins implementation will only ever pass a single boolean flag
-	// argument in the JSON request `args` field. The flag will be `--init` if it is
-	// attempting to get the flags for the `init` subcommand, `--api` for `create api`,
-	// `--webhook` for `create webhook`, and `--edit` for `edit`
-	if initFlag {
+	// argument in the JSON request `args` field. The flag will be `--edit` for `edit`
+	if editFlag {
 		// Populate the JSON response `metadata` field with a description
-		// and examples for the `init` subcommand
-		pluginResponse.Metadata = scaffolds.InitMeta
-	} else if apiFlag {
-		pluginResponse.Metadata = scaffolds.ApiMeta
-	} else if webhookFlag {
-		pluginResponse.Metadata = scaffolds.WebhookMeta
+		// and examples for the `edit` subcommand
+		pluginResponse.Metadata = scaffolds.EditMeta
 	} else {
 		pluginResponse.Error = true
 		pluginResponse.ErrorMsgs = []string{

docs/book/src/simple-external-plugin-tutorial/testdata/sampleexternalplugin/v1/go.mod

@@ -3,15 +3,20 @@ module v1
 go 1.24.5
 
 require (
+	github.com/spf13/afero v1.15.0
 	github.com/spf13/pflag v1.0.10
 	sigs.k8s.io/kubebuilder/v4 v4.9.0
 )
 
+replace sigs.k8s.io/kubebuilder/v4 => ../../../../../../../
+
 require (
 	github.com/gobuffalo/flect v1.0.3 // indirect
-	github.com/spf13/afero v1.15.0 // indirect
+	github.com/kr/text v0.2.0 // indirect
+	go.yaml.in/yaml/v2 v2.4.2 // indirect
 	golang.org/x/mod v0.28.0 // indirect
 	golang.org/x/sync v0.17.0 // indirect
 	golang.org/x/text v0.29.0 // indirect
 	golang.org/x/tools v0.37.0 // indirect
+	sigs.k8s.io/yaml v1.6.0 // indirect
 )

docs/book/src/simple-external-plugin-tutorial/testdata/sampleexternalplugin/v1/go.sum

@@ -1,5 +1,6 @@
 github.com/Masterminds/semver/v3 v3.4.0 h1:Zog+i5UMtVoCU8oKka5P7i9q9HgrJeGzI9SA1Xbatp0=
 github.com/Masterminds/semver/v3 v3.4.0/go.mod h1:4V+yj/TJE1HU9XfppCwVMZq3I84lprf4nC11bSS5beM=
+github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
@@ -13,12 +14,18 @@ github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
 github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
 github.com/google/pprof v0.0.0-20250820193118-f64d9cf942d6 h1:EEHtgt9IwisQ2AZ4pIsMjahcegHh6rmhqxzIRQIyepY=
 github.com/google/pprof v0.0.0-20250820193118-f64d9cf942d6/go.mod h1:I6V7YzU0XDpsHqbsyrghnFZLO1gwK6NPTNvmetQIk9U=
+github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
+github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
+github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
+github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
 github.com/onsi/ginkgo/v2 v2.25.3 h1:Ty8+Yi/ayDAGtk4XxmmfUy4GabvM+MegeB4cDLRi6nw=
 github.com/onsi/ginkgo/v2 v2.25.3/go.mod h1:43uiyQC4Ed2tkOzLsEYm7hnrb7UJTWHYNsuy3bG/snE=
 github.com/onsi/gomega v1.38.2 h1:eZCjf2xjZAqe+LeWvKb5weQ+NcPwX84kqJ0cZNxok2A=
 github.com/onsi/gomega v1.38.2/go.mod h1:W2MJcYxRGV63b418Ai34Ud0hEdTVXq9NW9+Sx6uXf3k=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ=
+github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc=
 github.com/spf13/afero v1.15.0 h1:b/YBCLWAJdFWJTN9cLhiXXcD7mzKn9Dm86dNnfyQw1I=
 github.com/spf13/afero v1.15.0/go.mod h1:NC2ByUVxtQs4b3sIUphxK0NioZnmxgyCrfzeuq8lxMg=
 github.com/spf13/pflag v1.0.10 h1:4EBh2KAYBwaONj6b2Ye1GiHfwjqyROoF4RwYO+vPwFk=
@@ -49,10 +56,10 @@ golang.org/x/text v0.29.0/go.mod h1:7MhJOA9CD2qZyOKYazxdYMF85OwPdEr9jTtBpO7ydH4=
 golang.org/x/tools v0.37.0 h1:DVSRzp7FwePZW356yEAChSdNcQo6Nsp+fex1SUW09lE=
 golang.org/x/tools v0.37.0/go.mod h1:MBN5QPQtLMHVdvsbtarmTNukZDdgwdwlO5qGacAzF0w=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
-sigs.k8s.io/kubebuilder/v4 v4.9.0 h1:9e9LnQy/wQ24IZDIqye6iZZFOB9aKNyNfjnfsy3S8cw=
-sigs.k8s.io/kubebuilder/v4 v4.9.0/go.mod h1:Xql7wLeyXBQ4lJJdi1Pl8T/DeV4UXpA1kaOEumN0pzY=
 sigs.k8s.io/yaml v1.6.0 h1:G8fkbMSAFqgEFgh4b1wmtzDnioxFCUgTZhlbj5P9QYs=
 sigs.k8s.io/yaml v1.6.0/go.mod h1:796bPqUfzR/0jLAl6XjHl3Ck7MiyVv8dbTdyT3/pMf4=

docs/book/src/simple-external-plugin-tutorial/testdata/sampleexternalplugin/v1/internal/test/plugins/prometheus/kustomization.go

@@ -0,0 +1,59 @@
+/*
+Copyright 2022 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 prometheus
+
+// PrometheusKustomization represents the kustomization.yaml for Prometheus resources
+type PrometheusKustomization struct {
+	Path    string
+	Content string
+}
+
+// NewPrometheusKustomization creates a new kustomization.yaml for Prometheus resources
+func NewPrometheusKustomization() *PrometheusKustomization {
+	return &PrometheusKustomization{
+		Path:    "config/prometheus/kustomization.yaml",
+		Content: prometheusKustomizationTemplate,
+	}
+}
+
+const prometheusKustomizationTemplate = `resources:
+  - monitor.yaml
+`
+
+// DefaultKustomizationPatch represents a patch to config/default/kustomization.yaml
+type DefaultKustomizationPatch struct {
+	Path    string
+	Content string
+}
+
+// NewDefaultKustomizationPatch creates a patch comment for the default kustomization.yaml
+func NewDefaultKustomizationPatch() *DefaultKustomizationPatch {
+	return &DefaultKustomizationPatch{
+		Path:    "config/default/kustomization_prometheus_patch.yaml",
+		Content: defaultKustomizationPatchTemplate,
+	}
+}
+
+const defaultKustomizationPatchTemplate = `# [PROMETHEUS] To enable prometheus monitor, uncomment the following line in config/default/kustomization.yaml:
+#
+# In the resources section, add:
+# - ../prometheus
+#
+# This will include the Prometheus ServiceMonitor in your deployment.
+# Make sure you have the Prometheus Operator installed in your cluster.
+#
+# For more information, see: https://github.com/prometheus-operator/prometheus-operator
+`

docs/book/src/simple-external-plugin-tutorial/testdata/sampleexternalplugin/v1/internal/test/plugins/prometheus/servicemonitor.go

@@ -0,0 +1,103 @@
+/*
+Copyright 2022 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 prometheus
+
+import "fmt"
+
+// ServiceMonitor represents a Prometheus ServiceMonitor manifest
+type ServiceMonitor struct {
+	Path    string
+	Content string
+}
+
+// ServiceMonitorOptions allows configuration of the ServiceMonitor
+type ServiceMonitorOptions func(*ServiceMonitor)
+
+// WithDomain sets the domain for the ServiceMonitor
+func WithDomain(domain string) ServiceMonitorOptions {
+	return func(sm *ServiceMonitor) {
+		sm.Content = fmt.Sprintf(serviceMonitorTemplate, domain, domain)
+	}
+}
+
+// WithProjectName sets the project name for the ServiceMonitor
+func WithProjectName(projectName string) ServiceMonitorOptions {
+	return func(sm *ServiceMonitor) {
+		// Project name can be used for labels or naming
+		// For now, we'll use it in a future iteration if needed
+	}
+}
+
+// NewServiceMonitor creates a new ServiceMonitor manifest
+func NewServiceMonitor(opts ...ServiceMonitorOptions) *ServiceMonitor {
+	sm := &ServiceMonitor{
+		Path: "config/prometheus/monitor.yaml",
+	}
+
+	for _, opt := range opts {
+		opt(sm)
+	}
+
+	// Set default content if not set by options
+	if sm.Content == "" {
+		sm.Content = fmt.Sprintf(serviceMonitorTemplate, "example.com", "example.com")
+	}
+
+	return sm
+}
+
+const serviceMonitorTemplate = `# Prometheus Monitor Service (Metrics)
+apiVersion: v1
+kind: Service
+metadata:
+  labels:
+    control-plane: controller-manager
+    app.kubernetes.io/name: %s
+    app.kubernetes.io/managed-by: kustomize
+  name: controller-manager-metrics-service
+  namespace: system
+spec:
+  ports:
+    - name: https
+      port: 8443
+      protocol: TCP
+      targetPort: 8443
+  selector:
+    control-plane: controller-manager
+
+---
+# Prometheus ServiceMonitor
+apiVersion: monitoring.coreos.com/v1
+kind: ServiceMonitor
+metadata:
+  labels:
+    control-plane: controller-manager
+    app.kubernetes.io/name: %s
+    app.kubernetes.io/managed-by: kustomize
+  name: controller-manager-metrics-monitor
+  namespace: system
+spec:
+  endpoints:
+    - path: /metrics
+      port: https
+      scheme: https
+      bearerTokenFile: /var/run/secrets/kubernetes.io/serviceaccount/token
+      tlsConfig:
+        insecureSkipVerify: true
+  selector:
+    matchLabels:
+      control-plane: controller-manager
+`