📖 Refactor sampleexternalplugin to be a Valid Reference Implementation by nerdeveloper · Pull Request #5116 · kubernetes-sigs/kubebuilder

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.

Details

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.

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!

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

 		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.

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

Copilot

Pull request overview

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

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

Copilot

Pull request overview

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

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

Copilot · 2026-01-07T07:20:14Z

+# Initialize a new project with Prometheus monitoring
+kubebuilder init --plugins sampleexternalplugin/v1


The documentation shows "Initialize a new project with Prometheus monitoring" as an example use case for the sampleexternalplugin, but this doesn't align with the actual test implementation. The test script uses 'kubebuilder init --plugins go/v4' first, then 'kubebuilder edit --plugins sampleexternalplugin/v1'. This suggests the plugin is meant to add Prometheus to an existing project, not during initialization. Either update the documentation example to reflect the actual usage pattern (adding Prometheus to an existing project), or ensure the init subcommand is properly tested and documented.

Copilot

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

Copilot

Pull request overview

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

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

camilamacedo86 · 2026-01-25T09:06:39Z

Hi @nerdeveloper

Can you please rebase with master this one?
I think then we can get merged and we can shape in follow ups.
WDYT?
Please ensure that you addressed either all Copilot review comments

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.

nerdeveloper · 2026-01-25T18:27:28Z

Hi @camilamacedo86,

Done! I've rebased the branch with the latest master and resolved the go.mod/go.sum conflicts.

Summary:

✅ Rebased with upstream master (single commit as required)
✅ All Copilot review comments were already addressed in previous updates
✅ Plugin builds successfully
✅ All tests pass

Ready for your review. Thanks!

camilamacedo86

/lgtm

Great work 🎉

/ok-to-test

k8s-ci-robot · 2026-01-26T13:31:06Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: camilamacedo86, nerdeveloper

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

The pull request process is described here

Details

Needs approval from an approver in each of these files:

~~OWNERS~~ [camilamacedo86]

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

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

Comment thread docs/book/src/plugins/extending/external-plugins.md Outdated

camilamacedo86 reviewed Oct 7, 2025

View reviewed changes

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

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

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

camilamacedo86 reviewed Nov 2, 2025

View reviewed changes

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

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

Copilot AI reviewed Jan 5, 2026

View reviewed changes

nerdeveloper force-pushed the refactor-sampleexternalplugin-issue-4824 branch 2 times, most recently from 7e2b248 to 9afd683 Compare January 5, 2026 13:38

nerdeveloper mentioned this pull request Jan 5, 2026

Add nerdeveloper to kubernetes and kubernetes-sigs orgs kubernetes/org#6047

Closed

6 tasks

camilamacedo86 requested a review from Copilot January 7, 2026 07:09

Copilot started reviewing on behalf of camilamacedo86 January 7, 2026 07:09 View session

Copilot AI reviewed Jan 7, 2026

View reviewed changes

nerdeveloper force-pushed the refactor-sampleexternalplugin-issue-4824 branch 2 times, most recently from e7f18f3 to ba09131 Compare January 7, 2026 10:07

camilamacedo86 requested a review from Copilot January 20, 2026 08:47

Copilot started reviewing on behalf of camilamacedo86 January 20, 2026 08:48 View session

Copilot AI reviewed Jan 20, 2026

View reviewed changes

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

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

nerdeveloper mentioned this pull request Jan 23, 2026

REQUEST: New membership for nerdeveloper kubernetes/org#6088

Closed

6 tasks

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

nerdeveloper force-pushed the refactor-sampleexternalplugin-issue-4824 branch from f1cb16c to eb76444 Compare January 25, 2026 18:26

k8s-ci-robot removed the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Jan 25, 2026

camilamacedo86 approved these changes Jan 26, 2026

View reviewed changes

k8s-ci-robot added ok-to-test Indicates a non-member PR verified by an org member that is safe to test. and removed needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. labels Jan 26, 2026

k8s-ci-robot assigned camilamacedo86 Jan 26, 2026

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Jan 26, 2026

k8s-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Jan 26, 2026

k8s-ci-robot merged commit 8393423 into kubernetes-sigs:master Jan 26, 2026
19 checks passed

nerdeveloper deleted the refactor-sampleexternalplugin-issue-4824 branch January 27, 2026 16:52

camilamacedo86 mentioned this pull request Jan 27, 2026

📖 docs(externalPluginSample): Improve external plugin sample with tests and validation #5398

Merged

		# Initialize a new project with Prometheus monitoring
		kubebuilder init --plugins sampleexternalplugin/v1

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!

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!

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!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI 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

Uh oh!

Uh oh!

Uh oh!

camilamacedo86 commented Jan 25, 2026

Uh oh!

nerdeveloper commented Jan 25, 2026

Uh oh!

camilamacedo86 left a comment

Choose a reason for hiding this comment

Uh oh!

k8s-ci-robot commented Jan 26, 2026

Uh oh!

Uh oh!

Reviewers

nerdeveloper commented Oct 5, 2025 •

edited

Loading

camilamacedo86 commented Nov 7, 2025 •

edited

Loading