🎉 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 . If your file does include , you may need a one-time upgrade, and can fully re-scaffold the project in one step. After that, updates work seamlessly. ()
This release updates Kubebuilder scaffolding to match controller-runtime v0.23.0. This version includes breaking changes that impact generated projects:
Type-safe webhook builder API — webhooks now use generics for stronger type safety
New Events API — migration from tools/record to tools/events
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:
(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)
(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
🌱 Bump github.com/onsi/ginkgo/v2 from 2.27.2 to 2.27.3 by @dependabot[bot] in https://github.com/kubernetes-sigs/kubebuilder/pull/5259
🌱 Bump github.com/spf13/cobra from 1.10.1 to 1.10.2 by @dependabot[bot] in https://github.com/kubernetes-sigs/kubebuilder/pull/5254
📖 (docs/quick-start): Fix generated controller file path by @shinebayar-g in https://github.com/kubernetes-sigs/kubebuilder/pull/5255
🌱 Bump github.com/onsi/gomega from 1.38.2 to 1.38.3 by @dependabot[bot] in https://github.com/kubernetes-sigs/kubebuilder/pull/5261
🌱 Bump golang.org/x/mod from 0.30.0 to 0.31.0 by @dependabot[bot] in https://github.com/kubernetes-sigs/kubebuilder/pull/5262
🌱 Bump golang.org/x/tools from 0.39.0 to 0.40.0 by @dependabot[bot] in https://github.com/kubernetes-sigs/kubebuilder/pull/5263
✨ (helm/v2alpha): Add support for parsing imagePullSecrets and including them in the generated chart by @zarcen in https://github.com/kubernetes-sigs/kubebuilder/pull/5242
🌱 Bump helm.sh/helm/v3 from 3.19.2 to 3.19.3 by @dependabot[bot] in https://github.com/kubernetes-sigs/kubebuilder/pull/5268
🌱 Bump helm.sh/helm/v3 from 3.19.3 to 3.19.4 by @dependabot[bot] in https://github.com/kubernetes-sigs/kubebuilder/pull/5271
🌱 Bump actions/upload-artifact from 5 to 6 by @dependabot[bot] in https://github.com/kubernetes-sigs/kubebuilder/pull/5270
📖 (docs): Fix duplicate content and collapse markers in writing tests tutorial by @BadisLaffet1 in https://github.com/kubernetes-sigs/kubebuilder/pull/5269
🌱 Change sort to slices package by @dongjiang1989 in https://github.com/kubernetes-sigs/kubebuilder/pull/5265
📖 Revamp migrations guides to reflect current tooling and options by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5233
📖 (doc): remove strict doc merged by mistake by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5272
🌱 Bump k8s.io/apimachinery from 0.34.2 to 0.34.3 by @dependabot[bot] in https://github.com/kubernetes-sigs/kubebuilder/pull/5267
🌱 Fix Doc Build after change the image used by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5274
📖 (docs): Add Go Reference badge to README by @vitorfloriano in https://github.com/kubernetes-sigs/kubebuilder/pull/5282
🌱 (infra/build): Remove Bazel config file by @vitorfloriano in https://github.com/kubernetes-sigs/kubebuilder/pull/5278
🌱 (infra/git): Remove .gitattributes file by @vitorfloriano in https://github.com/kubernetes-sigs/kubebuilder/pull/5279
✨ Upgrade go version from 1.24 to 1.25 by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5285
✨ (go/v4): Upgrade controller-gen from v0.19.0 to v0.20.0 by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5284
🌱 Bump k8s.io/apimachinery from 0.34.3 to 0.35.0 by @dependabot[bot] in https://github.com/kubernetes-sigs/kubebuilder/pull/5283
📖 Update Roadmap 2025 status by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5289
📖 Add docs: custom markers for unsupported file extensions by @nerdeveloper in https://github.com/kubernetes-sigs/kubebuilder/pull/5107
✨ (helm/v2-alpha) add tolerations, nodeselector and affinity by @robinlioret in https://github.com/kubernetes-sigs/kubebuilder/pull/5247
📖 Upgrade certmanager from v1.18.2 to v1.19.2 in the samples by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5292
✨ (go/v4): Upgrade cert-manager from v1.19.1 to v1.19.2 used by e2e test utilities by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5293
📖 Add 2026 Roadmap and Main Goals by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5290
🌱 Enhance AGENTS.md for Kubebuilder repo by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5296
📖 Update Roadmaps since with status of cronjob tutorials update by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5301
📖 docs: fix multiple documentation issues in RELEASE.md by @kube-gopher in https://github.com/kubernetes-sigs/kubebuilder/pull/5306
✨ (go/v4): Improve devcontainer for Codespaces compatibility by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5295
✨ (go/v4): Add AGENTS.md to the projects by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5273
📖 Update controller tests for tutorial samples by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5298
🐛 (alpha update): Fix --from-version Invalid SemVer error by @vitorfloriano in https://github.com/kubernetes-sigs/kubebuilder/pull/5309
📖 docs: Fix typo "UncommendCode" to "UncommentCode" in contributing guide by @kube-gopher in https://github.com/kubernetes-sigs/kubebuilder/pull/5312
📖 Update cronjob samples to fetch Cronjob resource before update by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5297
🌱 ci(security): add OpenSSF workflow and Scorecard badge by @vitorfloriano in https://github.com/kubernetes-sigs/kubebuilder/pull/5314
🌱 Bump github/codeql-action from 3 to 4 by @dependabot[bot] in https://github.com/kubernetes-sigs/kubebuilder/pull/5317
🌱 Bump actions/upload-artifact from 4.6.1 to 6.0.0 by @dependabot[bot] in https://github.com/kubernetes-sigs/kubebuilder/pull/5316
🌱 Bump ossf/scorecard-action from 2.4.1 to 2.4.3 by @dependabot[bot] in https://github.com/kubernetes-sigs/kubebuilder/pull/5319
🌱 Bump actions/checkout from 4.2.2 to 6.0.1 by @dependabot[bot] in https://github.com/kubernetes-sigs/kubebuilder/pull/5318
🌱 (fix) Allow use helm installed locally for e2e tests by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5320
✨ (go/v4): Improve the generated AGENTS.md guidance by fixing multi-group migration steps (API/controller/webhook moves) and standardizing the document layout by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5322
🌱 Fix testdata for new year by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5326
📖 (Manual Process to Migrate): Fix and enhance manual migration guide to keep instructions straightforward. by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5328
🐛 (fix): AGENTS.md generated with extra \ and missing hub info by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5327
📖 (docs) - Update multigroup layout change by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5321
📖 Manual process (migration guide): Add “AI Instructions Helper” examples to support end users. by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5324
🌱 Add support to k8s 1.35 by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5334
🐛 (go/v4): Fix E2E suite race condition that could delete cert-manager from environments inadvertently by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5329
🌱 Fix cmd version to keep value used by vendor by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5337
🐛 (go/v4): Re-add e2e cert-manager logs by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5338
🐛 (autoupdate/v1-alpha): Make GitHub Models opt-in to prevent 403 errors by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5333
🌱 Add test coverage for plugins by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5344
🌱 (test): Add missing kustomize/v2 and autoupdate plugins to coverage report by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5346
🌱 Increase coverage for the CLI/API by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5347
🐛 (CLI): Fix error unwrapping in updateFileModel for missing files by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5345
🌱 (test): Fix coverage config and exclude template directories by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5348
🌱 Add unit tests for CLI and external plugin helpers by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5350
📖 (doc) Streamline quick start plugins and next steps sections by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5342
✨ (alpha): Auto-migrate helm/v1-alpha to helm/v2-alpha in generate command by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5349
🐛 (go/v4): Support incremental webhook additions without losing custom code by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5353
🌱 chore: Move rashmigottipati and Kavinjsir to emeritus by @vitorfloriano in https://github.com/kubernetes-sigs/kubebuilder/pull/5341
✨ (helm/v2-alpha): Add nameOverride/fullnameOverride support and fix cert-manager templating by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5294
✨ (helm/v2-alpha): Improve generated values.yaml comment conventions (single # vs ##) by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5357
🐛 (helm/v2-alpha): add Helm standard labels to resources by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5340
✨ (helm/v2-alpha): add custom resources to templates/extras by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5339
✨ (helm/v2-alpha): improve _helpers.tpl readability by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5359
📖 (helm/v2-alpha): Update plugin docs to match actual chart output by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5363
🐛 (helm/v2-alpha): Fix force option to overwriten all files less Chart.yaml by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5361
🌱 Bump github.com/onsi/gomega from 1.38.3 to 1.39.0 by @dependabot[bot] in https://github.com/kubernetes-sigs/kubebuilder/pull/5366
🌱 Bump github.com/onsi/ginkgo/v2 from 2.27.3 to 2.27.4 by @dependabot[bot] in https://github.com/kubernetes-sigs/kubebuilder/pull/5367
🌱 Bump golang.org/x/mod from 0.31.0 to 0.32.0 by @dependabot[bot] in https://github.com/kubernetes-sigs/kubebuilder/pull/5368
🌱 Bump golang.org/x/text from 0.32.0 to 0.33.0 by @dependabot[bot] in https://github.com/kubernetes-sigs/kubebuilder/pull/5369
🌱 Bump github.com/onsi/ginkgo/v2 from 2.27.4 to 2.27.5 by @dependabot[bot] in https://github.com/kubernetes-sigs/kubebuilder/pull/5370
🌱 Bump golang.org/x/tools from 0.40.0 to 0.41.0 by @dependabot[bot] in https://github.com/kubernetes-sigs/kubebuilder/pull/5371
📖 (docs): Limit code rendering to relevant sections in multiversion webhook tutorial by @BadisLaffet1 in https://github.com/kubernetes-sigs/kubebuilder/pull/5372
🌱 Bump helm.sh/helm/v3 from 3.19.4 to 3.19.5 by @dependabot[bot] in https://github.com/kubernetes-sigs/kubebuilder/pull/5374
🐛 (helm/v2-alpha): Fix cross-namespace RBAC file naming and namespace handling by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5360
📖 Recommend options of migrations by @mloskot in https://github.com/kubernetes-sigs/kubebuilder/pull/5377
🌱 (ci): make e2e tests more robust for prow to avoid flakes by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5376
📖 docs: show only relevant webhook sections in kustomization tutorial by @BadisLaffet1 in https://github.com/kubernetes-sigs/kubebuilder/pull/5379
⚠️ Upgrade controller-runtime from v0.22.4 to v0.23.0 by @camilamacedo86 in https://github.com/kubernetes-sigs/kubebuilder/pull/5378
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