kubernetes-sigs/kubebuilder v4.11.0 on GitHub

🚀 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:

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

New Contributors

@mdbooth made their first contribution in #5245
@BadisLaffet1 made their first contribution in #5257
@shinebayar-g made their first contribution in #5255
@zarcen made their first contribution in #5242
@robinlioret made their first contribution in #5247
@kube-gopher made their first contribution in #5306
@mloskot made their first contribution in #5377

Full Changelog: v4.10.1...v4.11.0