📖 Refactor sampleexternalplugin to be a Valid Reference Implementation #5116

nerdeveloper · 2025-10-05T14:49:24Z

Summary

This PR refactors the sampleexternalplugin from outdated mock scaffolding into a realistic, working reference implementation that demonstrates best practices for external plugin development.

Problem

The current sampleexternalplugin (issue #4824) had several issues:

❌ Mock scaffolding that created useless text files (initFile.txt, apiFile.txt)
❌ Didn't use PROJECT config or align with internal plugin architecture
❌ Used release module instead of local source for testing
❌ Not a realistic example for plugin developers

Solution

Transformed the plugin into a Prometheus Monitoring Generator that:

✅ Uses edit subcommand to add optional Prometheus monitoring features
✅ Reads PROJECT config for domain and project metadata
✅ Generates real ServiceMonitor YAML manifests
✅ Uses local Kubebuilder source via replace directive
✅ Follows internal plugin architecture patterns

Changes

Plugin Functionality

Removed: Mock init, create api, create webhook subcommands
Added: Realistic edit subcommand that scaffolds Prometheus monitoring
Implements: PROJECT config reading (domain, projectName, repo)
Generates:
- config/prometheus/monitor.yaml - ServiceMonitor resource
- config/prometheus/kustomization.yaml - Kustomize config
- config/default/kustomization_prometheus_patch.yaml - Integration instructions

Code Quality

Uses config.Config APIs like internal plugins
Proper Universe pattern for file scaffolding
Local source replace directive: replace sigs.k8s.io/kubebuilder/v4 => ../../../../../../../

Documentation

Updated external-plugins.md with realistic edit command examples
Changed examples from mock init/api/webhook to real Prometheus monitoring use case

Usage Example

# Add Prometheus monitoring to your operator project
kubebuilder edit --plugins sampleexternalplugin/v1

This will scaffold:

Prometheus ServiceMonitor configuration
Kustomize resources for monitoring
Integration instructions

Testing

✅ Plugin builds successfully with local source
✅ All mock files removed, real templates in place
✅ Documentation reflects new usage

Impact

This PR makes the sample plugin a proper reference that:

Shows how to read PROJECT config in external plugins
Demonstrates real-world use case (optional monitoring features)
Allows contributors to test against local Kubebuilder source
Aligns with internal plugin architecture patterns

Fixes #4824

k8s-ci-robot · 2025-10-05T14:49:33Z

Hi @nerdeveloper. Thanks for your PR.

I'm waiting for a kubernetes-sigs member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

k8s-ci-robot · 2025-10-05T14:49:35Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: nerdeveloper
Once this PR has been reviewed and has the lgtm label, please assign varshaprasad96 for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

vitorfloriano · 2025-10-06T12:43:50Z

Hi @nerdeveloper thanks for the PR! This is a large one and will take some time to review. While you wait for the review, could you please adjust the title so it follows the guidelines for PR titles? Also, could you squash the four commits into one just so we keep the rule of a single commit per PR? Thanks!

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

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

camilamacedo86

Thank you for your contribution 🥇
I tried give the first round of reviews, let me know wdyt.

Copilot

Pull Request Overview

This PR refactors the sampleexternalplugin from mock scaffolding into a realistic Prometheus monitoring generator that demonstrates best practices for external plugin development. The plugin now uses the edit subcommand to add optional monitoring features by reading PROJECT config and generating actual ServiceMonitor YAML manifests.

Key Changes:

Removed mock init, create api, and create webhook subcommands in favor of realistic edit subcommand
Implemented PROJECT config reading using config.Config APIs similar to internal plugins
Added local source replace directive for testing against local Kubebuilder source

Reviewed Changes

Copilot reviewed 20 out of 21 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
`v1/scaffolds/init.go`	Updated to scaffold Prometheus monitoring resources during initialization
`v1/scaffolds/edit.go`	New file implementing edit subcommand with PROJECT config loading
`v1/scaffolds/api.go`	Removed - mock create api subcommand deleted
`v1/scaffolds/webhook.go`	Removed - mock create webhook subcommand deleted
`v1/internal/test/plugins/prometheus/prometheus.go`	New Prometheus instance manifest template
`v1/internal/test/plugins/prometheus/kustomization.go`	New kustomization templates for Prometheus resources
`v1/cmd/cmd.go`	Updated command routing to support init and edit only
`v1/cmd/metadata.go`	Updated to handle init and edit metadata requests
`v1/cmd/flags.go`	Refactored flag handling for init and edit subcommands
`v1/go.mod`	Added afero dependency and local source replace directive
`v1/test/test.sh`	Updated test to verify Prometheus asset scaffolding
`external-plugins.md`	Updated documentation with realistic edit command examples
`v1/testdata/testplugin/*`	Removed mock test files
`v1/scaffolds/internal/templates/*`	Removed mock template files

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2025-10-27T08:06:04Z

docs/book/src/simple-external-plugin-tutorial/testdata/sampleexternalplugin/v1/test/test.sh

+kubebuilder edit --plugins sampleexternalplugin/v1
+
+# Ensure Prometheus assets were scaffolded
+test -f config/prometheus/prometheus.yaml


The test checks for prometheus.yaml but the code scaffolds the file at path config/prometheus/prometheus.yaml according to prometheus.go line 47. The filename should be prometheus.yaml, not monitor.yaml as mentioned in the PR description.

Copilot · 2025-10-27T08:06:04Z

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

 		pluginResponse.Error = true
 		pluginResponse.ErrorMsgs = []string{
-			"unrecognized command: " + pr.Command,
+			"unrecognized subcommand flag in args: " + string(rune(len(pr.Args))),


Converting len(pr.Args) to a rune and then to a string produces a Unicode character, not a numeric string. This will result in confusing error messages. Use strconv.Itoa(len(pr.Args)) or fmt.Sprintf(\"%d\", len(pr.Args)) instead.

.../book/src/simple-external-plugin-tutorial/testdata/sampleexternalplugin/v1/scaffolds/edit.go

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

...-tutorial/testdata/sampleexternalplugin/v1/internal/test/plugins/prometheus/kustomization.go

nerdeveloper · 2025-11-06T10:40:31Z

@camilamacedo86 should I also implement the copilot suggestions?

camilamacedo86 · 2025-11-07T14:11:28Z

Hi @nerdeveloper

@camilamacedo86 should I also implement the copilot suggestions?

You need here:

Rebase the PR with master -> Ensure that the example cover the latest changes
Address all comments / reviews that make sense -> We have been using AI to help out, so if the comment/suggestion made by Copilot make sense we should address as well
Ensure that all pass on the CI/tests
Ensure that we have only 1 commit for the PR
Ensure that the changes made in the sample are accurate, will better clarify how to extend the lib to create external type plugins with a more practical / valid use case scenario.

I hope that can helps out.
Thank you for looking on that 🎉

Transform the sample external plugin from mock scaffolding to a realistic Prometheus monitoring generator that demonstrates best practices for external plugin development. Key changes: - Implement init and edit subcommands that scaffold Prometheus instance manifests - Add PROJECT config reading to align with internal plugin patterns - Replace mock ServiceMonitor with complete Prometheus CR including RBAC - Add --namespace flag support to demonstrate argument passing - Update documentation with realistic examples showing argument usage - Fix error handling to properly validate PROJECT file existence - Add comprehensive kustomization manifests for Prometheus resources The plugin now serves as a proper reference implementation for: - Reading PROJECT configuration in external plugins - Scaffolding production-ready Kubernetes manifests - Supporting command-line arguments (--namespace flag) - Testing plugins against local Kubebuilder source - Adding optional monitoring features via edit subcommand Addresses maintainer feedback on PR kubernetes-sigs#5116 including proper error handling, argument passing examples, and realistic manifest generation. Fixes kubernetes-sigs#4824

Transform the sample external plugin from mock scaffolding to a realistic Prometheus monitoring generator that demonstrates best practices for external plugin development. Key changes: - Implement init and edit subcommands that scaffold Prometheus instance manifests - Add PROJECT config reading to align with internal plugin patterns - Replace mock ServiceMonitor with complete Prometheus CR including RBAC - Add --namespace flag support to demonstrate argument passing - Update documentation with realistic examples showing argument usage - Fix error handling to properly validate PROJECT file existence - Centralize kustomization in config/default/kustomization.yaml (no separate prometheus kustomization) - Provide clear instructions for users to add Prometheus resources manually The plugin now serves as a proper reference implementation for: - Reading PROJECT configuration in external plugins - Scaffolding production-ready Kubernetes manifests - Supporting command-line arguments (--namespace flag) - Testing plugins against local Kubebuilder source - Adding optional monitoring features via edit subcommand - Following Kubebuilder's centralized kustomization pattern Addresses maintainer feedback on PR kubernetes-sigs#5116 including proper error handling, argument passing examples, realistic manifest generation, and centralized kustomization. Fixes kubernetes-sigs#4824

Transform the sample external plugin from mock scaffolding to a realistic Prometheus monitoring generator that demonstrates best practices for external plugin development. Key changes: - Implement init and edit subcommands that scaffold Prometheus instance manifests - Add PROJECT config reading to align with internal plugin patterns - Replace mock ServiceMonitor with complete Prometheus CR including RBAC - Add --namespace flag support to demonstrate argument passing - Update documentation with realistic examples showing argument usage - Fix error handling to properly validate PROJECT file existence - Centralize kustomization in config/default/kustomization.yaml (no separate prometheus kustomization) - Provide clear instructions for users to add Prometheus resources manually The plugin now serves as a proper reference implementation for: - Reading PROJECT configuration in external plugins - Scaffolding production-ready Kubernetes manifests - Supporting command-line arguments (--namespace flag) - Testing plugins against local Kubebuilder source - Adding optional monitoring features via edit subcommand - Following Kubebuilder's centralized kustomization pattern Addresses maintainer feedback on PR 5116 including proper error handling, argument passing examples, realistic manifest generation, and centralized kustomization.

camilamacedo86 · 2025-11-10T05:24:04Z

...gin-tutorial/testdata/sampleexternalplugin/v1/internal/test/plugins/prometheus/prometheus.go

+subjects:
+- kind: ServiceAccount
+  name: prometheus
+  namespace: %s


We would need scaffold each of them in the respective place
For example, rbac in the config/rbac dir.
Also, have we not those already?

camilamacedo86 · 2025-11-10T05:24:35Z

...gin-tutorial/testdata/sampleexternalplugin/v1/internal/test/plugins/prometheus/prometheus.go

+  namespace: %s
+  labels:
+    app.kubernetes.io/name: %s
+    app.kubernetes.io/managed-by: kustomize


We have a Service Account already, would we need another one?

camilamacedo86 · 2025-11-10T05:25:30Z

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

-    "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 instance configuration for monitoring your operator.",
+    "examples": "kubebuilder edit --plugins sampleexternalplugin/v1 --namespace monitoring"


What does it means namespace monitoring?
Why this flag would be required?

Copilot

Pull Request Overview

Copilot reviewed 20 out of 21 changed files in this pull request and generated 7 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2025-11-10T05:32:44Z

.../book/src/simple-external-plugin-tutorial/testdata/sampleexternalplugin/v1/scaffolds/init.go

-		}
-		return pluginResponse
+	// For init command, we'll use default values since PROJECT file may not exist yet
+	projectConfig := &ProjectConfig{


The ProjectConfig type is used here but is only defined in edit.go. This will cause a compilation error. Either move the ProjectConfig type definition to a shared location or duplicate it in this file.

Copilot · 2025-11-10T05:32:44Z

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

  "universe": {
-    "initFile": "A file created with the `init` subcommand."
+    "config/prometheus/prometheus.yaml": "# Prometheus instance manifest with RBAC...",
+    "config/prometheus/kustomization.yaml": "resources:\n  - prometheus.yaml\n",


The documentation example shows config/prometheus/kustomization.yaml being created in the universe (line 100), but the actual implementation doesn't scaffold this file. This inconsistency between documentation and implementation could mislead users. Either update the documentation to match the actual files created or modify the plugin to scaffold this file.

Suggested change

"config/prometheus/kustomization.yaml": "resources:\n - prometheus.yaml\n",

Copilot · 2025-11-10T05:32:45Z

.../book/src/simple-external-plugin-tutorial/testdata/sampleexternalplugin/v1/scaffolds/edit.go

+	// Parse namespace flag from args
+	namespace := "default"
+	for i, arg := range pr.Args {
+		if arg == "--namespace" && i+1 < len(pr.Args) {
+			namespace = pr.Args[i+1]
+			break
+		}
+	}


Manual flag parsing is error-prone and doesn't handle edge cases properly. This approach doesn't handle scenarios like --namespace=monitoring (equals syntax), missing value after --namespace, or unknown flags. Consider using pflag.NewFlagSet() for proper flag parsing, similar to how it was done in the deleted code (api.go, webhook.go).

Copilot · 2025-11-10T05:32:45Z

...gin-tutorial/testdata/sampleexternalplugin/v1/internal/test/plugins/prometheus/prometheus.go

+// WithProjectName sets the project name for the Prometheus instance
+func WithProjectName(projectName string) PrometheusOptions {
+	return func(p *PrometheusInstance) {
+		// Project name can be used for labels or naming
+		// For now, we'll use it in a future iteration if needed
+	}
+}
+


The WithProjectName option function is defined but doesn't actually do anything with the projectName parameter. This creates a misleading API where users might expect it to have an effect. Either implement the functionality or remove this option entirely until it's needed.

Suggested change

// WithProjectName sets the project name for the Prometheus instance

func WithProjectName(projectName string) PrometheusOptions {

return func(p *PrometheusInstance) {

// Project name can be used for labels or naming

// For now, we'll use it in a future iteration if needed

}

}

Copilot · 2025-11-10T05:32:45Z

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

 	} else {
 		pluginResponse.Error = true
 		pluginResponse.ErrorMsgs = []string{


The error message "unrecognized flag" is vague and doesn't help users understand what went wrong or what flags are expected. Consider providing more helpful information such as "no subcommand flag provided; expected --init or --edit".

Copilot · 2025-11-10T05:32:46Z

docs/book/src/simple-external-plugin-tutorial/testdata/sampleexternalplugin/v1/test/test.sh

+
+# Ensure Prometheus assets were scaffolded
+test -f config/prometheus/prometheus.yaml
+test -f config/prometheus/kustomization.yaml


The test script expects config/prometheus/kustomization.yaml to be created, but the plugin only scaffolds config/prometheus/prometheus.yaml and config/default/kustomization_prometheus_patch.yaml. Either add code to scaffold the missing kustomization.yaml file or remove this test assertion.

Suggested change

test -f config/prometheus/kustomization.yaml

Copilot · 2025-11-10T05:32:46Z

.../book/src/simple-external-plugin-tutorial/testdata/sampleexternalplugin/v1/scaffolds/edit.go

+	}
+
+	// Parse namespace flag from args
+	namespace := "default"


The default namespace is set to "default" when the flag is not provided, but in the NewPrometheusInstance function (prometheus.go line 58), the default namespace is "system". This inconsistency could lead to confusion. Consider aligning these defaults or making the logic more explicit.

Suggested change

namespace := "default"

namespace := "system"

k8s-ci-robot added do-not-merge/invalid-commit-message Indicates that a PR should not merge because it has an invalid commit message. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. labels Oct 5, 2025

k8s-ci-robot added needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. labels Oct 5, 2025

k8s-ci-robot requested review from camilamacedo86 and varshaprasad96 October 5, 2025 14:49

nerdeveloper force-pushed the refactor-sampleexternalplugin-issue-4824 branch from 63b82e0 to edc4046 Compare October 5, 2025 14:51

nerdeveloper changed the title ~~✨ Refactor sampleexternalplugin to be a Valid Reference Implementation~~ Refactor sampleexternalplugin to be a Valid Reference Implementation Oct 5, 2025

nerdeveloper force-pushed the refactor-sampleexternalplugin-issue-4824 branch from d42c0be to 5395def Compare October 5, 2025 16:48

k8s-ci-robot removed the do-not-merge/invalid-commit-message Indicates that a PR should not merge because it has an invalid commit message. label Oct 5, 2025

camilamacedo86 reviewed Oct 7, 2025

View reviewed changes

docs/book/src/plugins/extending/external-plugins.md Outdated Show resolved Hide resolved

camilamacedo86 reviewed Oct 7, 2025

View reviewed changes

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

camilamacedo86 requested changes Oct 14, 2025

View reviewed changes

nerdeveloper requested a review from camilamacedo86 October 27, 2025 04:09

camilamacedo86 requested a review from Copilot October 27, 2025 08:05

camilamacedo86 changed the title ~~Refactor sampleexternalplugin to be a Valid Reference Implementation~~ 📖 Refactor sampleexternalplugin to be a Valid Reference Implementation Oct 27, 2025

Copilot AI reviewed Oct 27, 2025

View reviewed changes

k8s-ci-robot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Nov 1, 2025

camilamacedo86 reviewed Nov 2, 2025

View reviewed changes

docs/book/src/plugins/extending/external-plugins.md Show resolved Hide resolved

camilamacedo86 reviewed Nov 2, 2025

View reviewed changes

...-tutorial/testdata/sampleexternalplugin/v1/internal/test/plugins/prometheus/kustomization.go Show resolved Hide resolved

nerdeveloper force-pushed the refactor-sampleexternalplugin-issue-4824 branch from 9d001d4 to 8c61760 Compare November 10, 2025 03:56

k8s-ci-robot added do-not-merge/invalid-commit-message Indicates that a PR should not merge because it has an invalid commit message. and removed needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. labels Nov 10, 2025

nerdeveloper force-pushed the refactor-sampleexternalplugin-issue-4824 branch from 8c61760 to 8efb648 Compare November 10, 2025 04:04

nerdeveloper force-pushed the refactor-sampleexternalplugin-issue-4824 branch from 8efb648 to 5b04b5e Compare November 10, 2025 04:08

nerdeveloper force-pushed the refactor-sampleexternalplugin-issue-4824 branch from 5b04b5e to 036056e Compare November 10, 2025 04:14

k8s-ci-robot removed the do-not-merge/invalid-commit-message Indicates that a PR should not merge because it has an invalid commit message. label Nov 10, 2025

nerdeveloper requested a review from camilamacedo86 November 10, 2025 04:16

camilamacedo86 requested a review from Copilot November 10, 2025 05:22

camilamacedo86 reviewed Nov 10, 2025

View reviewed changes

Copilot AI reviewed Nov 10, 2025

View reviewed changes

📖 Refactor sampleexternalplugin to be a Valid Reference Implementation #5116

Are you sure you want to change the base?

📖 Refactor sampleexternalplugin to be a Valid Reference Implementation #5116

Conversation

nerdeveloper commented Oct 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Problem

Solution

Changes

Plugin Functionality

Code Quality

Documentation

Usage Example

Testing

Impact

Uh oh!

k8s-ci-robot commented Oct 5, 2025

Uh oh!

k8s-ci-robot commented Oct 5, 2025

Uh oh!

vitorfloriano commented Oct 6, 2025

Uh oh!

Uh oh!

Uh oh!

camilamacedo86 left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Oct 27, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 27, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

nerdeveloper commented Nov 6, 2025

Uh oh!

camilamacedo86 commented Nov 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

camilamacedo86 Nov 10, 2025

Choose a reason for hiding this comment

Uh oh!

camilamacedo86 Nov 10, 2025

Choose a reason for hiding this comment

Uh oh!

camilamacedo86 Nov 10, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Copilot AI Nov 10, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 10, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 10, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 10, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 10, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 10, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 10, 2025

Choose a reason for hiding this comment

nerdeveloper commented Oct 5, 2025 •

edited

Loading

camilamacedo86 commented Nov 7, 2025 •

edited

Loading