github kubernetes-sigs/kubebuilder v4.3.0
on GitHub

18 hours ago

⚠️ Important Notice:

(Only projects using webhooks are impacted by)

Controller runtime has deprecated the webhook.Validator and webhook.Defaulter interfaces, and they will no longer be provided in future versions. Therefore, projects must adopt the new CustomValidator and CustomDefaulter interfaces to remain compatible with controller-runtime v0.20.0 and upper versions. For more details, refer to controller-runtime/issues/2641.

Furthermore, webhooks should no longer reside under the api directory. Instead, they should be relocated to internal/webhook. For now, you can scaffold webhooks in the legacy path (under api) by using the command kubebuilder create webhook [OPTIONS] --legacy=true, which scaffolds using the CustomValidator and CustomDefaulter interfaces. However, please note that this flag is deprecated and will be removed in upcoming releases.

Steps to Migrate:

  1. Move Webhook Files to the Internal Directory:

    Depending on your project structure, move the webhook files:

    • Single Group Layout: Move from api/<version> to internal/webhook/<version>.

      Before: 

      api/
├── <version>/
│   ├── <kind>_webhook.go
│   ├── <kind>_webhook_test.go
│   └── webhook_suite_test.go

      After: 

      internal/
├── webhook/
│   └── <version>/
│       ├── <kind>_webhook.go
│       ├── <kind>_webhook_test.go
│       └── webhook_suite_test.go

    • Multigroup Layout: Move from api/<group>/<version> to internal/webhook/<group>/<version>.

      Before: 

      api/
├── <group>/
│   └── <version>/
│       ├── <kind>_webhook.go
│       ├── <kind>_webhook_test.go
│       └── webhook_suite_test.go

      After: 

      internal/
├── webhook/
│   └── <group>/
│       └── <version>/
│           ├── <kind>_webhook.go
│           ├── <kind>_webhook_test.go
│           └── webhook_suite_test.go

  2. Update Imports:

    After moving the files, ensure that all references to webhooks are updated in your main.go and other files. For example, update the import:

    • Before: 

      import "your_project/api/v1"

    • After: 

      import "your_project/internal/webhook/v1"

  3. Replace Deprecated Interfaces with Custom Ones:

    Replace webhook.Validator and webhook.Defaulter with the new CustomValidator and CustomDefaulter interfaces:

    • Before: 

      var _ webhook.Validator = &MyResource{}

func (r *MyResource) ValidateCreate() error { ... }
func (r *MyResource) ValidateUpdate() error { ... }
func (r *MyResource) ValidateDelete() error { ... }

var _ webhook.Defaulter = &MyResource{}

func (r *MyResource) Default() { ... }

    • After: 

      var _ webhook.CustomValidator = &MyResource{}

func (v *MyResource) ValidateCreate(ctx context.Context, obj runtime.Object) (admission.Warnings, error) {
    myResource, ok := obj.(*MyResource)
    if !ok { return nil, fmt.Errorf("expected MyResource, got %T", obj) }
    return nil, validateMyResource(myResource)
}

func (v *MyResource) ValidateUpdate(ctx context.Context, oldObj, newObj runtime.Object) (admission.Warnings, error) {
    myResource, ok := newObj.(*MyResource)
    if !ok { return nil, fmt.Errorf("expected MyResource, got %T", newObj) }
    return nil, validateMyResource(myResource)
}

func (v *MyResource) ValidateDelete(ctx context.Context, obj runtime.Object) (admission.Warnings, error) {
    myResource, ok := obj.(*MyResource)
    if !ok { return nil, fmt.Errorf("expected MyResource, got %T", obj) }
    return nil, nil
}

var _ webhook.CustomDefaulter = &MyResource{}

func (d *MyResource) Default(ctx context.Context, obj runtime.Object) error {
    myResource, ok := obj.(*MyResource)
    if !ok { return fmt.Errorf("expected MyResource, got %T", obj) }
    // Defaulting logic
    return nil
}

Example: See the tutorial: CronJob Webhook Example.

Note: You might want to use the Upgrade Assistance to re-scaffold your project and then apply your code changes on top, ensuring that all necessary updates are addressed. Also,

⚠️ Breaking Changes

  • (Only projects using webhooks are impacted by) (go/v4): Replaced the deprecated webhook.Validator and webhook.Defaulter interfaces with CustomValidator and CustomDefaulter. Projects using the old interfaces must migrate to ensure compatibility with future versions. (#4060)
  • (Only projects using webhooks are impacted by) (go/v4): Webhooks are now decoupled from the API directory. Webhook files should be moved from api/<version> or api/<group>/<version> to internal/webhook/<version> or internal/webhook/<group>/<version>. This restructuring improves project organization. (#4150)
  • (Impact only for library users): Removed the APIPackagePathLegacy method, which has been obsolete since release 4.0.0. This change cleans up unused code. (#4182)
  • (Impact only for library users): cleanup/refactor: Alpha Generate command. Move code source implementation to internal since this alpha feature is not designed to be imported by other tools (#4180)
  • (Impact only for library users): Removed the redundant HasFragment method, favoring HasFileContentWith to reduce duplication and simplify the codebase. (#4191)

✨ New Features

  • (go/v4): Added DevContainer support, making development in environments like GitHub Workspaces easier by removing the need for local setup. (#4078)
  • (go/v4): The e2e test scaffolding has been improved with a comprehensive set of tests under e2e/tests, covering the manager and webhooks. These tests are designed to fail when not run against clusters using Kind, and they avoid re-installing Prometheus and Cert-Manager if already present. See the final scaffolded tests in the samples under testdata here. Key improvements include:
    • Added checks to detect existing Prometheus and Cert-Manager installations to prevent re-installation. (#4117)
    • Enhanced e2e tests to ensure proper execution with Kind and clarified usage. (#4106)
    • Ensured make manifests and make generate are run as part of the e2e tests. (#4122)
    • Aligned make test-e2e with make test for consistent behavior. (#4125)
    • Improved tests to validate metrics endpoints and ensure proper metric exposure, including guidance for using metrics in reconciliation validation. (#4131)
    • Added support for scaffolded e2e webhook tests with the +kubebuilder:scaffold:e2e-webhooks-checks marker. (#4121)
    • Simplified Gomega assertions for better readability and improved error handling and logging in e2e/test.go. (#4141, #4158, #4166, #4175)
  • (go/v4): Improved the webhook tests by adding examples. Also, enhanced the CronJob tutorial to clarify usage and validate changes. (#4130)
  • (deploy-image/v1alpha): Improved the tests scaffolded for controllers to ensure better coverage. (#4197)
  • (go/v4): Added support for scaffolding controllers and webhooks for External Types, making it easier to work with external resources in projects. (#4171, #4203, #4217)
  • (go/v4): Add Support for Scaffolding Webhooks for Core Types (#4210)
  • (go/v4): Upgraded the cert-manager version used in tests from v1.14.4 to v1.16.0 for better compatibility and features. (#4209)
  • (deploy-image/v1-alpha1): Added comments to clarify how resource watching and reconciliation logic works in the scaffolded code. (#4102)
  • (go/v4): Upgrade controller-tools version from v0.16.1 to v0.16.4 (#4215)
  • (go/v4): Upgrade Prometheus Operator version used on the tests from v0.72.0 to 0.77.1 (#4212)

🐛 Bug Fixes

  • (deploy-image/v1-alpha1): Corrected a typo, replacing typeNamespaceName with typeNamespacedName to ensure accurate variable naming. (#4100)
  • (deploy-image/v1-alpha1): Fixed sample code to apply correct labels to resources, improving consistency in the scaffolded examples. (#4101)
  • (go/v4): Resolved linter issues in the scaffold, adding nolint where necessary to prevent failures for specific cases that should not fail during checks. (#4111)
  • (deploy-image/v1-alpha1): Addressed additional linter issues to enhance code quality. (#4112)
  • (go/v4): Fixed linter issues to pass stricter checks like godot, gofumpt, and nlreturn, ensuring better code formatting and style. (#4133)
  • (go/v4): Removed duplicate webhook names in multi-version APIs, resolving conflicts when using the same webhook names across different API versions. (#4145)
  • (go/v4): Improved webhook test templates by adding examples, providing clearer guidance for testing webhooks. (#4151)
  • (go/v4): Ensured unique controller names to fix naming conflicts in multigroup layouts, improving support for projects with multiple groups. (#4162)
  • (go/v4): Fixed the HasResource package method to stop once a match is found, improving performance and accuracy in resource handling. (#4190)
  • (go/v4, kustomize/v2): Simplified scaffold by removing webhookcainjection_patch and clarified the use of cert-manager as a replacement. (#4123)
  • (go/v4, kustomize/v2): fixed Duplicate Webhook Patch Entries when Creating Multiple Versions (#4220)

What's Changed

  • ✨ (go/v4): Added DevContainer support for seamless development in environments like GitHub Workspaces without local setup. by @TAM360 in #4078
  • 📖 Update docs support by @camilamacedo86 in #4058
  • 📖 update the next step from quick start accordingly by @camilamacedo86 in #4092
  • 📖 provide better info about usage of kind by @camilamacedo86 in #4091
  • 📖 Minor Documentation Improvements: Add Links, Fix Typos, and Clarify Instructions by @camilamacedo86 in #4093
  • 🌱 (ci) - Fix the job to check the PR title and no longer use deprecated github action by @camilamacedo86 in #4095
  • 🌱 ci: Normalize text-based emoji codes to actual emojis in PR title checker by @camilamacedo86 in #4097
  • 🌱 move pr title checker to be under test with ther others checks by @camilamacedo86 in #4099
  • 🐛 (deploy-image/v1-alpha1): Fix typo issue by replacing typeNamespaceName with typeNamespacedName by @camilamacedo86 in #4100
  • 📖 remove warning note which was valid for old k8s versions by @camilamacedo86 in #4098
  • 🐛 (deploy-image/v1-alpha1): Fix sample by ensuring the right labels by @camilamacedo86 in #4101
  • 📖 remove notes about crd-version and webhook-version flags which are no longer supported and provided by @camilamacedo86 in #4104
  • 📖 fix link for reference doc to manager and crd scopes by @camilamacedo86 in #4105
  • 🌱 Bump actions/checkout from 3 to 4 by @dependabot in #4108
  • 🌱 Bump github.com/onsi/ginkgo/v2 from 2.20.0 to 2.20.1 by @dependabot in #4107
  • 🐛 (go/v4): Fix linter issues in the scaffold by @camilamacedo86 in #4111
  • 🐛 (deployimage/v1apha1): fix linter issues by @camilamacedo86 in #4112
  • 🌱 ci: fix e2e tests for samples by @camilamacedo86 in #4114
  • ✨ (go/v4) e2e tests: improve e2e tests and make test-e2e target by @camilamacedo86 in #4106
  • 🌱 ci: no longer call github actions for changes which are only made in the docs files (/.md) by @camilamacedo86 in #4115
  • 🌱 ci- cleanup lint samples by @camilamacedo86 in #4113
  • 🐛 (go/v4): fix test e2e by ensuring that make manifests and generate are executed as part of the tests by @camilamacedo86 in #4122
  • 🌱 ci: fix GitHub action to test make test-e2e for deploy-image by @camilamacedo86 in #4118
  • ✨ (go/v4):Added checks in the e2e test scaffolds to determine if Prometheus and/or CertManager are already installed on the cluster and avoid re-installation. by @Adembc in #4117
  • 🐛 fix: ensure that make test-e2e call the same targets of make test by @camilamacedo86 in #4125
  • ✨ (deploy-image/v1-alpha1): Add comments to clarify resource watching and reconciliation logic by @camilamacedo86 in #4102
  • ⚠️ : (go/v4): Replace usage of deprecated webhook.Validator and webhook.Defaulter interfaces by @camilamacedo86 in #4060
  • 🌱 Bump github.com/onsi/ginkgo/v2 from 2.20.1 to 2.20.2 by @dependabot in #4127
  • 📖 Improve and Simplify the Getting Started Guide by @camilamacedo86 in #4094
  • 📖 update and supplement webhook documentation with example to work with core types by @camilamacedo86 in #4061
  • 🌱 Bump github.com/onsi/gomega from 1.34.1 to 1.34.2 by @dependabot in #4128
  • 🌱 fix testdata/project-v4 samples by removing call to generate Lakers controller without resource by @camilamacedo86 in #4129
  • ✨ (go/v4) Add Metrics Validation and Helper Functions to E2E Tests by @mogsie in #4131
  • 🐛 (go/v4): fix linter issues to allow pass in the stricter linter checks such as; godot, gofumpt, nlreturn by @pgaxatte in #4133
  • ✨ (go/v4): improve the webhook tests by adding examples. Also, improve cronjob tutorial to clarify its usage and validate the changes by @camilamacedo86 in #4130
  • ✨ (go/v4) Add scaffold for e2e webhook checks by @camilamacedo86 in #4121
  • 🌱 cleanup: Replace "-m=64" with "--memory-limit=64" by @mogsie in #4136
  • 📖 update multi-version with the latest changes and address fixes by @camilamacedo86 in #4139
  • 🌱 cleanup plugin_cluster-test.go by @mogsie in #4137
  • ✨ (go/v4): cleanup: in e2e/test.go, make Gomega assertions more concise by @mogsie in #4141
  • 📖 cleanup: improves cronjob_controller_test.go gomega assertions by @mogsie in #4142
  • 🐛 (go/v4) resolve duplicate webhook name issue in multi-version API by @camilamacedo86 in #4145
  • 🌱 Automatically update the multiversion tutorial by @camilamacedo86 in #4138
  • 🌱 ci: add ci job to run the e2e tests for the samples used in the tutor… by @camilamacedo86 in #4147
  • 🌱 Bump golang.org/x/text from 0.17.0 to 0.18.0 by @dependabot in #4152
  • 🌱 Bump golang.org/x/tools from 0.24.0 to 0.25.0 by @dependabot in #4153
  • 🐛 Enhances the webhook test template. by @mogsie in #4151
  • 🌱 cleanup: simplify and consolidate testdata samples by @camilamacedo86 in #4126
  • 🌱 cleanup: simplify and consolidate testdata samples #4126 by @camilamacedo86 in #4157
  • 📖 fix marker for webhook server in the tutorial samples and position of explanations by @camilamacedo86 in #4155
  • 🌱 add better coverage to pkg/machinery/marker by @camilamacedo86 in #4156
  • 🐛 (go/v4): Refactor e2e-tests for clearer error handling and readable logs by @camilamacedo86 in #4158
  • 🐛 fix: ensure unique controller names to fix name conflicts in multigroup setup by @camilamacedo86 in #4162
  • 🌱 ci: add e2e tests for multigroup testdata layout and rename sample by @camilamacedo86 in #4154
  • 📖 Simplify event recording example by @rkosegi in #4165
  • ✨ (go/v4) Add GitHub Actions by @camilamacedo86 in #4110
  • 🐛 (go/v4): Follow -up: Refactor e2e-tests for clearer error handling and readable logs by @camilamacedo86 in #4166
  • 🌱 e2e-tests: fix/cleanup and add test to validate webhooks outside of the manager namespace by @camilamacedo86 in #4167
  • 📖 remove from getting started the link for watching resources since this doc acctually document predicates by @camilamacedo86 in #4169
  • 📖 Add new documentation explaining the usage of Pprof by @TAM360 in #4160
  • 📖 : add documentation about kubebuilder:scaffold marker by @camilamacedo86 in #4173
  • ✨ (go/v4): e2e tests: add data collection on failures and code simplification by @camilamacedo86 in #4175
  • 📖 Revamp "Watching Resources" documentation for accuracy and clarifty by @camilamacedo86 in #4170
  • 📖 Update README.md - Clarify that monthly Kubebuilder sync meetings are scheduled but most syncing happens offline via Slack by @camilamacedo86 in #4172
  • 📖 add note to clarify markers in the doc by @camilamacedo86 in #4174
  • 🐛 cleanup: remove func APIPackagePathLegacy which is no longer used since release 4.0.0 by @camilamacedo86 in #4182
  • 📖 (doc) remove from menu Appendix: The TODO Landing Page by @camilamacedo86 in #4186
  • 📖 (doc): remove section in the platform documentation which says that kube-rbac-proxy is an image provided by default by @camilamacedo86 in #4187
  • 🌱 add to be ignored .DS_Store by @camilamacedo86 in #4189
  • ⚠️ 🐛fix: remove duplicate HasFragment method, replaced by HasFileContentWith by @camilamacedo86 in #4191
  • 🐛 Fix HasResource pkg method to properly stop when a match is found by @camilamacedo86 in #4190
  • 🌱cleanup/refactor: Implement and refactor e2e tests for 'alpha generate' command by @camilamacedo86 in #4181
  • 📖 (doc): remove Makefile Helpers by @camilamacedo86 in #4184
  • 🌱 Bump github.com/gobuffalo/flect from 1.0.2 to 1.0.3 by @dependabot in #4194
  • ✨ (deploy-image/v1alpha): Improve tests scaffolded for the controllers by @mogsie in #4197
  • ⚠️ (go/v4) decouple webhooks from APIs (Move Webhooks from api/<version> or api/<group>/<version> to internal/webhook/<version> or internal/webhook/<group>/<version>) by @camilamacedo86 in #4150
  • ✨ Add support to scaffold controllers for External Types by @camilamacedo86 in #4171
  • 📖 docs: update migration_guide_gov3_to_gov4.md by @lorenzofelletti in #4204
  • 🌱 fix: replace references to v3 package with v4 by @camilamacedo86 in #4206
  • 🌱 Bump golang.org/x/tools from 0.25.0 to 0.26.0 by @dependabot in #4207
  • ✨ Upgrade cert-manager version used on the tests from v1.14.4 to v1.16.0 by @camilamacedo86 in #4209
  • 📖 small fixes for the doc Using External Resources by @camilamacedo86 in #4211
  • 📖 (doc) - refactory and clenup the Plugin section by @camilamacedo86 in #4185
  • ✨ Upgrade controller-tools version from v0.16.1 to v0.16.4 by @camilamacedo86 in #4215
  • ⚠️ cleanup/refactor: Alpha Generate command by @camilamacedo86 in #4180
  • 🐛 (go/v4,kustomize/v2): Fix problems by simplify scaffold and removing webhookcainjection_patch. Clarifying replacements for cert-manager by @camilamacedo86 in #4123
  • ✨ Upgrade Prometheus Operator version used on the tests from v0.72.0 to 0.77.1 by @camilamacedo86 in #4212
  • 📖 Update roadmap_2024.md - Complete goal to align webhook scaffold with the latest changes in controller-runtime by @camilamacedo86 in #4216
  • 📖 (doc) - Fix typo issues in the tutorial scaffolded samples (replace indicies with indices) by @monteiro-renato in #4219
  • 🐛 fixed Duplicate Webhook Patch Entries when Creating Multiple Ver… by @Bharadwajshivam28 in #4220
  • ✨ Add support to scaffold webhooks for External Types by @camilamacedo86 in #4203
  • ✨ Add Support for Scaffolding Webhooks for Core Types by @camilamacedo86 in #4210
  • 🐛 fix support for external types by allowing the domain be empty, and properly generate the sample for cert-manager. by @camilamacedo86 in #4217
  • 🌱 fix GoReleaser by adding permission to write content by @camilamacedo86 in #4226

New Contributors

Full Changelog: v4.2.0...v4.3.0

Check out latest releases or
releases around kubernetes-sigs/kubebuilder v4.3.0

Don't miss a new kubebuilder release

NewReleases is sending notifications on new releases.

Get notifications