🚀 Keep Your Scaffold Updated

🎉 Our migration guide was fully updated to help you upgrade from any version to the latest. It also now includes AI migration helpers/commands to guide upgrades for old scaffolds where manual steps are required. See the migrations guidance.

Automate updates with kubebuilder edit --plugins="autoupdate.kubebuilder.io/v1-alpha" or run them manually with kubebuilder alpha update. If your PROJECT file does not include cliVersion, you may need a one-time upgrade, and kubebuilder alpha generate can fully re-scaffold the project in one step. After that, updates work seamlessly. (More info)

⚠️ Breaking changes

controller-runtime v0.23.0 upgrade (v0.22.4 → v0.23.0)

This release updates Kubebuilder scaffolding to match controller-runtime v0.23.0. This version includes breaking changes that impact generated projects:

1. Type-safe webhook builder API — webhooks now use generics for stronger type safety
2. New Events API — migration from tools/record to tools/events
3. ENVTEST teardown — testEnv.Stop() now requires an Eventually wrapper for graceful shutdown

• For manual upgrade steps for older projects, see: https://github.com/kubernetes-sigs/kubebuilder/pull/5378
• For the full upstream change list, see controller-runtime v0.23.0 release notes: https://github.com/kubernetes-sigs/controller-runtime/releases/tag/v0.23.0

If you use the Helm plugin to distribute your project

This release includes major Helm plugin changes (community-raised fixes and improvements have been addressed). Please update your project:

• If you use helm/v1-alpha: upgrade to helm/v2-alpha. Using kubebuilder alpha generate or kubebuilder alpha update will re-scaffold your project and auto-migrate Helm v1 → v2.

• If you use helm/v2-alpha and you update manually (not via kubebuilder alpha generate / kubebuilder alpha update, or neither has the AutoUpdate Plugin configured), then re-generate the chart with all fixes:

kubebuilder edit --plugins=helm/v2-alpha --force

If you have customisations, back up your current Helm chart first so you can re-apply them on top of the latest version.

Tip: Check the PROJECT file to see which plugin/version your project is using.

✨ New features

• (helm/v2-alpha): Add tolerations, nodeSelector, and affinity support. (#5247)
• (go/v4): Improve devcontainer for Codespaces compatibility. (#5295)
• (go/v4): Add AGENTS.md to generated projects. (#5273, #5322, #5327)
• (alpha): Auto-migrate helm/v1-alpha projects to helm/v2-alpha during generate. (#5349)
• (helm/v2-alpha): Improve _helpers.tpl readability. (#5359)
• (helm/v2-alpha): Standardise generated values.yaml comment conventions (single # vs ##). (#5357)
• (helm/v2-alpha): Add standard Helm labels to generated resources. (#5340)
• (helm/v2-alpha): Add custom resources to templates/extras. (#5339)
• (helm/v2-alpha): Add support for parsing imagePullSecrets and including them in the generated chart. (#5242)

✨ Upgrades

• (go/v4): Upgrade controller-runtime from v0.22.4 to v0.23.0. (#5378)
• (go/v4): Upgrade golangci-lint from v2.5.0 → v2.7.2. (#5221, #5258)
• (go/v4): Upgrade Go version from 1.24 → 1.25. (#5285)
• (go/v4): Upgrade controller-gen from v0.19.0 → v0.20.0. (#5284)
• (go/v4): Upgrade cert-manager used by e2e test utilities from v1.19.1 → v1.19.2. (#5293)

🐛 Bug fixes

• (go/v4): Remove redundant config/webhook/kustomizeconfig.yaml and config/crd/kustomizeconfig.yaml (Kustomize v3.5.4+ has built-in support), fixing namespace transformation issues when using projects as bases/overlays. (#5245, #5243)
• (alpha update): Fix --from-version “Invalid SemVer” error. (#5309)
• (go/v4): Fix e2e suite race condition that could inadvertently delete cert-manager from environments. (#5329)
• (go/v4): Re-add cert-manager logs to e2e runs. (#5338)
• (autoupdate/v1-alpha): Make GitHub Models opt-in to prevent 403 errors. (#5333)
• (CLI): Fix error unwrapping in updateFileModel when files are missing. (#5345)
• (go/v4): Support incremental webhook additions without overwriting custom code. (#5353)
• (helm/v2-alpha): Add nameOverride/fullnameOverride support and fix cert-manager templating. (#5294)
• (helm/v2-alpha): Fix --force behaviour to overwrite all files except Chart.yaml. (#5361)
• (helm/v2-alpha): Fix cross-namespace RBAC file naming and namespace handling. (#5360)

🎉 Thanks to all contributors!

What's Changed ( Full Changelog )

• 🌱 Upgrade github.com/joelanford/go-apidiff from v0.6.1 to v0.8.3 by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5222
• ✨ (go/v4): Upgrade golangci-lint from v2.5.0 to v2.6.0 by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5221
• 🌱 (ci): Config action to test release only when we push against master branch by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5223
• 📖 (doc): Move section Versions Compatibility and Supportability for references by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5226
• 📖 (doc): Improve note for deploy image plugin in quick start by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5225
• 📖 (doc): Update note about The Bootstrapping Problem by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5228
• 📖 (docs): Remove epilog since no info has been added on it by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5231
• 📖 Update badge for latest release in README.md by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5234
• 📖 Bump sigs.k8s.io/kubebuilder/v4 from 4.9.0 to 4.10.1 in /docs/book/src/simple-external-plugin-tutorial/testdata/sampleexternalplugin/v1 by @dependabot[bot] in https://github.com/kubernetes-sigs/kubebuilder/pull/5235
• 📖 (doc): Improve note about other examples for the tests by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5230
• 📖 (doc): Improve note in the quick start to use autoupdate by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5224
• 📖 Migrate to mdBook v0.5.0 by @vitorfloriano in https://github.com/kubernetes-sigs/kubebuilder/pull/5207
• 🐛 Removed config/webhook/kustomizeconfig.yaml and config/crd/kustomizeconfig.yaml - these are redundant since Kustomize v3.5.4+ has built-in support. This also fixes namespace transformation bugs when using projects as Kustomize bases/overlays. by @mdbooth in https://github.com/kubernetes-sigs/kubebuilder/pull/5245
• 🌱 Add vitorfloriano as reviewer by @vitorfloriano in https://github.com/kubernetes-sigs/kubebuilder/pull/5252
• 🌱 Bump actions/checkout from 5 to 6 by @dependabot[bot] in https://github.com/kubernetes-sigs/kubebuilder/pull/5243
• ✨ (go/v4): Upgrade golangci-lint to v2.7.2 and add modernize check by @dongjiang1989 in https://github.com/kubernetes-sigs/kubebuilder/pull/5258
• 🌱 Bump golang.org/x/text from 0.31.0 to 0.32.0 by @dependabot[bot] in https://github.com/kubernetes-sigs/kubebuilder/pull/5260
• 📖 (docs): Show webhook configuration in cronjob tutorial by @BadisLaffet1 in https://github.com/kubernetes-sigs/kubebuilder/pull/5257

New Contributors

• @mdbooth made their first contribution in https://github.com/kubernetes-sigs/kubebuilder/pull/5245
• @BadisLaffet1 made their first contribution in https://github.com/kubernetes-sigs/kubebuilder/pull/5257
• @shinebayar-g made their first contribution in https://github.com/kubernetes-sigs/kubebuilder/pull/5255
• @zarcen made their first contribution in https://github.com/kubernetes-sigs/kubebuilder/pull/5242
• @robinlioret made their first contribution in https://github.com/kubernetes-sigs/kubebuilder/pull/5247
• @kube-gopher made their first contribution in https://github.com/kubernetes-sigs/kubebuilder/pull/5306
• @mloskot made their first contribution in https://github.com/kubernetes-sigs/kubebuilder/pull/5377

Full Changelog: https://github.com/kubernetes-sigs/kubebuilder/compare/v4.10.1...v4.11.0