Release v4.12.0: Help test changes and review before the release + planner

[camilamacedo86]

This issue tracks the changes planned for the next major Kubebuilder release 4.12.0and asks the community to review them before we cut the release.

Note: Anything merged into master before the release is cut will also be included.

Please comment if:

• you find any issue in the listed changes, or
• something important is missing and should be part of this release.

Thank you for the help! 🙌

PS.: To help test, please pull the master branch locally and run:

make install

See: https://github.com/kubernetes-sigs/kubebuilder/blob/master/CONTRIBUTING.md#how-to-build-kubebuilder-locally

----------- Following the draft for the next release 4.12.0 -------------------------

🚀 Keep Your Scaffold Updated

The migration guide covers upgrading from any version to the latest, including AI-assisted helpers/commands for legacy scaffolds that may require manual steps. For the smoothest path, enable the AutoUpdate Plugin (uses GitHub Actions)) or run kubebuilder alpha update locally—both use the same update logic. The other options are primarily for older projects missing cliVersion in the PROJECT file as a one-time step to reach a supported version; after that, you can rely on these workflows for ongoing updates.

✨ Upgrades

• (go/v4): upgrade golangci-lint from v2.7.2 to v2.8.1. (✨ (go/v4): upgrade golangci-lint from v2.7.2 to v2.8.0 #5403, ✨ (kustomize/v2) Upgrade kustomize from 5.8.0 to 5.8.1 #5481)
• (kustomize/v2): Upgrade kustomize from 5.7.1 to 5.8.0. (✨ (kustomize/v2): Upgrade kustomize from 5.7.1 to 5.8.0 #5412)
• (go/v4): Upgrade certmanager from v1.19.2 to v1.19.3. (✨ Upgrade certmanager from v1.19.2 to v1.19.3 #5431)
• (go/v4): Upgrade controller-tools from v0.20.0 to v0.20.1 (✨ chore(go/v4): Upgrade controller-tools from v0.20.0 to v0.20.1 #5475)

✨ New features

• (helm/v2-alpha): Polish Chart.yaml metadata. (✨ (helm/v2-alpha): polish Chart.yaml metadata #5414)
• (helm/v2-alpha): Add Notes.txt. (✨ (helm/v2-alpha): Add Notes.txt #5392)
• (helm/v2-alpha): Add Makefile targets for Helm Development. (✨ (helm/v2-alpha): Add Makefile targets for Helm Development #5442,✨ feat(helm/v2-alpha): Add install-helm target and upgrade to Helm 4 #5468)
• (go/v4): Add autocomplete support in .devcontainer/post-install.sh and enhance script. (✨ (go/v4): Add autocomplete support in .devcontainer/post-install.sh #5394, ✨(go/v4): enhance devcontainer post-install script #5435)
• (go/v4): Add custom k8s linter for logs to promote better observability. (✨ (go/v4): Add custom k8s linter for logs to promote better observability #5396)
• (go/v4): Now, users can scaffold projects which are namespace-scoped managers by using the flag --namespaced. The flag is valid for init and edit subcommands (✨ (go/v4): Add --namespaced flag for namespace-scoped managers #5411, ✨ (go/v4): Add webhook scope mismatch warning for namespace-scoped mode #5482, 🐛 (go/v4): preserve existing PROJECT values for unset edit flags #5480)
• (go/v4): add --multigroup flag to init subcommand. Now you can initialize a project with this layout (✨ (go/v4): add --multigroup flag to init command #5440)
• (CLI): Add short description to tab completion in bash . (✨ feat(cli): add short description to tab completion in bash #5408)
• (alpha/update): Add the flag --merge-message and flag --conflict-message to allow customise commit messages. (✨ (alpha/update): add flags for custom commit messages #5429, ✨ refactor(alpha/update): shorten commit message flag names #5479)

🐛 Bug fixes

• (go/v4): Follow Kubernetes logging conventions. (🐛 (go/v4): Follow Kubernetes logging conventions #5406)
• (helm/v2-alpha): wrap webhook resources with .Values.webhook.enable conditional. (🐛 (helm/v2-alpha): wrap webhook resources with .Values.webhook.enable conditional #5413)
• (helm/v2-alpha): Fix chart generation and template rendering issues. (🐛 (helm/v2-alpha): Fix chart generation and template rendering issues #5422)
• (helm/v2-alpha): Support custom container names and fix templating bugs (🐛 (helm/v2-alpha): Support custom container names and fix templating bugs #5463)
• (helm/v2-alpha): Fix crd.keep to correctly add the helm.sh/resource-policy: keep annotation to generated CRDs (🐛 (helm/v2-alpha): Fix crd.keep to correctly add the helm.sh/resource-policy: keep annotation to generated CRDs #5472)
• (CLI): alpha generate/update now respect custom project name. (🐛 fix(alpha): respect custom project name in generate command #5426)
• (alpha/update): update commit messages with conventional commit format. (🐛 (alpha/update): update commit messages with conventional commit format #5428)
• (helm/v2-alpha): remove deprecated helm/v1-alpha plugin entry from PROJECT file when helm/v2-alpha is used. (🐛 (helm/v2-alpha): remove deprecated v1-alpha plugin entry from PROJECT file #5436)
• (go/v4): Make e2e tests more robust to avoid flakes (🐛 fix(go/v4): Add retry to flaky metrics E2E test #5437, 🐛 fix(go/v4): Add more checks for webhooks in e2e tests to avoid flakes #5450)
• (CLI/API): FIx issues when --help command was used with --plugins and improve output to show the available help plugins per subcommand. (🐛 fix(CLI/API) prevent --help from being validated as plugin name #5448)
• (API): move hack/docs/utils to hack/docs/internal. (🐛 fix(api): move hack/docs/utils to hack/docs/internal #5407)

🎉 Thanks to all contributors!

What's Changed ( Full Changelog )

• ✨ (go/v4): upgrade golangci-lint from v2.7.2 to v2.8.0 by @camilamacedo86 in ✨ (go/v4): upgrade golangci-lint from v2.7.2 to v2.8.0 #5403
• 📖 (docs): Clarify PR title and commit message format guidelines by @camilamacedo86 in 📖 (docs): Clarify PR title and commit message format guidelines #5393
• ✨ (go/v4): Add autocomplete support in .devcontainer/post-install.sh by @camilamacedo86 in ✨ (go/v4): Add autocomplete support in .devcontainer/post-install.sh #5394
• 🐛 fix(api): move hack/docs/utils to hack/docs/internal by @vitorfloriano in 🐛 fix(api): move hack/docs/utils to hack/docs/internal #5407
• 📖 docs(externalPluginSample): Improve external plugin sample with tests and validation by @camilamacedo86 in 📖 docs(externalPluginSample): Improve external plugin sample with tests and validation #5398
• ✨ feat(cli): add short description to tab completion in bash by @vitorfloriano in ✨ feat(cli): add short description to tab completion in bash #5408
• 🐛 (go/v4): Follow Kubernetes logging conventions by @camilamacedo86 in 🐛 (go/v4): Follow Kubernetes logging conventions #5406
• 📖 Add webhook bootstrap problem guide and warning by @camilamacedo86 in 📖 Add webhook bootstrap problem guide and warning #5395
• ✨ (go/v4): Add custom k8s linter for logs to promote better observability by @camilamacedo86 in ✨ (go/v4): Add custom k8s linter for logs to promote better observability #5396
• 🌱 (agents.md): enhance the AI instructions for Kubebuilder logging by @camilamacedo86 in 🌱 (agents.md): enhance the AI instructions for Kubebuilder logging #5410
• ✨ (kustomize/v2): Upgrade kustomize from 5.7.1 to 5.8.0 by @camilamacedo86 in ✨ (kustomize/v2): Upgrade kustomize from 5.7.1 to 5.8.0 #5412
• 🐛 (helm/v2-alpha): wrap webhook resources with .Values.webhook.enable conditional by @camilamacedo86 in 🐛 (helm/v2-alpha): wrap webhook resources with .Values.webhook.enable conditional #5413
• 📖 Bump github.com/onsi/ginkgo/v2 from 2.27.5 to 2.28.1 in /docs/book/src/simple-external-plugin-tutorial/testdata/sampleexternalplugin/v1 by @dependabot[bot] in 📖 Bump github.com/onsi/ginkgo/v2 from 2.27.5 to 2.28.1 in /docs/book/src/simple-external-plugin-tutorial/testdata/sampleexternalplugin/v1 #5420
• 📖 Bump github.com/onsi/gomega from 1.39.0 to 1.39.1 in /docs/book/src/simple-external-plugin-tutorial/testdata/sampleexternalplugin/v1 by @dependabot[bot] in 📖 Bump github.com/onsi/gomega from 1.39.0 to 1.39.1 in /docs/book/src/simple-external-plugin-tutorial/testdata/sampleexternalplugin/v1 #5418
• 🌱 Bump github.com/onsi/gomega from 1.39.0 to 1.39.1 by @dependabot[bot] in 🌱 Bump github.com/onsi/gomega from 1.39.0 to 1.39.1 #5417
• 🌱 Bump github.com/onsi/ginkgo/v2 from 2.27.5 to 2.28.1 by @dependabot[bot] in 🌱 Bump github.com/onsi/ginkgo/v2 from 2.27.5 to 2.28.1 #5419
• 📖 (docs/infra): Update mdBook version to v0.5.2 by @ottnorml in 📖 (docs/infra): Update mdBook version to v0.5.2 #5421
• 🐛 CLI release version): Preserve clean version tags in GoReleaser builds by @camilamacedo86 in 🐛 CLI release version): Preserve clean version tags in GoReleaser builds #5424
• 🐛 (helm/v2-alpha): Fix chart generation and template rendering issues by @camilamacedo86 in 🐛 (helm/v2-alpha): Fix chart generation and template rendering issues #5422
• 🐛 fix(alpha): respect custom project name in generate command by @camilamacedo86 in 🐛 fix(alpha): respect custom project name in generate command #5426
• 🐛 (alpha/update): update commit messages with conventional commit format by @camilamacedo86 in 🐛 (alpha/update): update commit messages with conventional commit format #5428
• 🐛 fix(CLI): Fix logs to follow best practices by @camilamacedo86 in 🐛 fix(CLI): Fix logs to follow best practices #5409
• 🌱 Fix lint issue - size of message by @camilamacedo86 in 🌱 Fix lint issue - size of message #5432
• ✨ Upgrade certmanager from v1.19.2 to v1.19.3 by @camilamacedo86 in ✨ Upgrade certmanager from v1.19.2 to v1.19.3 #5431
• ✨ (alpha/update): add flags for custom commit messages by @camilamacedo86 in ✨ (alpha/update): add flags for custom commit messages #5429
• 🌱 test(e2e): centralize test helpers and optimize test execution by @camilamacedo86 in 🌱 test(e2e): centralize test helpers and optimize test execution #5427
• ✨ (helm/v2-alpha): polish Chart.yaml metadata by @camilamacedo86 in ✨ (helm/v2-alpha): polish Chart.yaml metadata #5414
• ✨ (helm/v2-alpha): Add Notes.txt by @camilamacedo86 in ✨ (helm/v2-alpha): Add Notes.txt #5392
• 🐛 (helm/v2-alpha): remove deprecated v1-alpha plugin entry from PROJECT file by @camilamacedo86 in 🐛 (helm/v2-alpha): remove deprecated v1-alpha plugin entry from PROJECT file #5436
• 🐛 fix(go/v4): Add retry to flaky metrics E2E test by @camilamacedo86 in 🐛 fix(go/v4): Add retry to flaky metrics E2E test #5437
• ✨(go/v4): enhance devcontainer post-install script by @camilamacedo86 in ✨(go/v4): enhance devcontainer post-install script #5435
• 📖 : remove misleading comment from install script by @orangecms in 📖 : remove misleading comment from install script #5439
• ✨ (go/v4): Add --namespaced flag for namespace-scoped managers by @camilamacedo86 in ✨ (go/v4): Add --namespaced flag for namespace-scoped managers #5411
• 🌱 (e2e/docs): Update certmanager to v1.19.3 and prometheus to v0.85.0 by @camilamacedo86 in 🌱 (e2e/docs): Update certmanager to v1.19.3 and prometheus to v0.85.0 #5441
• 🐛 fix(CLI/API) prevent --help from being validated as plugin name by @camilamacedo86 in 🐛 fix(CLI/API) prevent --help from being validated as plugin name #5448
• 🐛 fix(go/v4): Add more checks for webhooks in e2e tests to avoid flakes by @camilamacedo86 in 🐛 fix(go/v4): Add more checks for webhooks in e2e tests to avoid flakes #5450
• 🌱 fix(e2e): consolidate test suites to reduce execution time by @camilamacedo86 in 🌱 fix(e2e): consolidate test suites to reduce execution time #5454
• 📖 docs: add note on limitations to CRD validation markers reference by @orangecms in 📖 docs: add note on limitations to CRD validation markers reference #5438
• 🌱 docs/book: fix the install script by @orangecms in 🌱 docs/book: fix the install script #5455
• ✨ (helm/v2-alpha): Add Makefile targets for Helm Development by @camilamacedo86 in ✨ (helm/v2-alpha): Add Makefile targets for Helm Development #5442
• 🌱 Bump golang.org/x/tools from 0.41.0 to 0.42.0 by @dependabot[bot] in 🌱 Bump golang.org/x/tools from 0.41.0 to 0.42.0 #5460
• ✨ (helm/v2-alpha): Add Helm chart tests and call in the GitHub action to validate the chart by @camilamacedo86 in ✨ (helm/v2-alpha): Add Helm chart tests and call in the GitHub action to validate the chart #5415
• 📖 CONTRIBUTING: reference mdBook's advanced Markdown format by @orangecms in 📖 CONTRIBUTING: reference mdBook's advanced Markdown format #5464
• 🐛 (helm/v2-alpha): Support custom container names and fix templating bugs by @AlirezaPourchali in 🐛 (helm/v2-alpha): Support custom container names and fix templating bugs #5463
• 🌱 Bump k8s.io/apimachinery from 0.35.0 to 0.35.1 by @dependabot[bot] in 🌱 Bump k8s.io/apimachinery from 0.35.0 to 0.35.1 #5467
• ✨ (go/v4): add --multigroup flag to init command by @camilamacedo86 in ✨ (go/v4): add --multigroup flag to init command #5440
• 🌱 Update external plugin sample Go deps by @camilamacedo86 in 🌱 Update external plugin sample Go deps #5469
• 🌱 refactor(kustomize/v2): follow Go logging conventions for webhook warning by @camilamacedo86 in 🌱 refactor(kustomize/v2): follow Go logging conventions for webhook warning #5470
• ✨ feat(helm/v2-alpha): Add install-helm target and upgrade to Helm 4 by @camilamacedo86 in ✨ feat(helm/v2-alpha): Add install-helm target and upgrade to Helm 4 #5468
• 🐛 (helm/v2-alpha): Fix crd.keep to correctly add the helm.sh/resource-policy: keep annotation to generated CRDs by @asergeant01 in 🐛 (helm/v2-alpha): Fix crd.keep to correctly add the helm.sh/resource-policy: keep annotation to generated CRDs #5472
• 🐛 fix(helm/v2-alpha): remove issues to pre-load image by @camilamacedo86 in 🐛 fix(helm/v2-alpha): remove issues to pre-load image #5477
• ✨ chore(go/v4): Upgrade controller-tools from v0.20.0 to v0.20.1 by @camilamacedo86 in ✨ chore(go/v4): Upgrade controller-tools from v0.20.0 to v0.20.1 #5475
• ⚠️ (helm/v2-alpha): remove helm test added (reverts pre-release addition to be safe) by @camilamacedo86 in ⚠️ (helm/v2-alpha): remove helm test added (reverts pre-release addition to be safe) #5478
• ✨ refactor(alpha/update): shorten commit message flag names by @camilamacedo86 in ✨ refactor(alpha/update): shorten commit message flag names #5479

New Contributors

• @ottnorml made their first contribution in 📖 (docs/infra): Update mdBook version to v0.5.2 #5421
• @orangecms made their first contribution in 📖 : remove misleading comment from install script #5439
• @AlirezaPourchali made their first contribution in 🐛 (helm/v2-alpha): Support custom container names and fix templating bugs #5463
• @asergeant01 made their first contribution in 🐛 (helm/v2-alpha): Fix crd.keep to correctly add the helm.sh/resource-policy: keep annotation to generated CRDs #5472

Full Changelog: v4.11.1...master

[nerdeveloper]

Hey Camila, I took some time to look at this and you can correct me if I'm wrong on any of these, but a few things stood out:

1. Kustomize v5.8.0 has a known regression (PR #5412)

The kustomize v5.8.0 release page has this notice at the top:

IMPORTANT NOTICE: REGRESSION
Due to the new features introduced in this release, a regression has occurred in the functionality that propagates namespaces to child kustomizations. We are currently preparing a patch release, so please refrain from making changes to this version.

Since every newly scaffolded project pins KUSTOMIZE_VERSION ?= v5.8.0 in the Makefile, that means make deploy and make build-installer could silently produce manifests with broken namespace config. Not sure if this has already been caught but figured it was worth flagging.

2. --namespaced doesn't account for webhooks (PR #5411)

The --namespaced flag restricts the manager's cache to WATCH_NAMESPACE, but webhooks are inherently cluster-scoped — MutatingWebhookConfiguration and ValidatingWebhookConfiguration are cluster-level resources. So a namespace-scoped manager running webhooks would still receive admission requests for resources in namespaces it's not watching. If the webhook handler tries to look up an object that's not in the restricted cache, that could be a problem at runtime. The webhook server in cmd/main.go is set up identically in both modes.

3. edit command silently clears boolean flags (PRs #5411, #5440)

Both --namespaced and --multigroup default to false in the edit command's BindFlags. Since Scaffold() unconditionally calls SetX()/ClearX() based on the flag values, running something like kubebuilder edit --namespaced would silently clear multigroup because it defaults to false, and vice versa.

[camilamacedo86]

Hi @nerdeveloper

Thank you for the amazing review !!
Following the status and comments inline

1. Kustomize v5.8.0 has a known regression (PR ✨ (kustomize/v2): Upgrade kustomize from 5.7.1 to 5.8.0 #5412)

It is fixed now. We are bumping 5.8.1 👍
#5481

2. --namespaced doesn't account for webhooks (PR ✨ (go/v4): Add --namespaced flag for namespace-scoped managers #5411)

You are right. The solution is use namespaceSelector or objectSelectors but controller-gen does not provide markers to solve that see: kubernetes-sigs/controller-tools#553 and kubernetes-sigs/controller-tools#1338

So, we can make it more clear for now, and when it be supported there we can tray to streamlining the implementation. See: #5482

3. edit command silently clears boolean flags (PRs ✨ (go/v4): Add --namespaced flag for namespace-scoped managers #5411, ✨ (go/v4): add --multigroup flag to init command #5440)

Amazing catcher !! 🥇
See the fix for this bug: #5480

Now, once we have all merged/addressed I think we can release !!

[camilamacedo86]

DONE 🎉
thank you for all help !!!