Migrations

Upgrading your Kubebuilder project to the latest version ensures you benefit from new features, bug fixes, and ecosystem improvements. It is recommended to keep your project aligned with ecosystem changes.

Migration may involve updating to a newer plugin version (e.g., from go.kubebuilder.io/v3 in release 3.x to go.kubebuilder.io/v4 in release 4.x) or updating the scaffold produced by the same plugin across CLI releases (e.g., from v4.9.0 to v4.10.1).

Kubebuilder provides multiple migration paths to suit your workflow. Choose the approach that best fits your needs.

Project Customizations

After using the CLI to create your project, you are free to customize the business logic and add features as you see fit. However, it is not recommended to deviate from the proposed project layout unless you know what you are doing.

For example, you should refrain from moving the scaffolded files, as doing so may will make it difficult to upgrade your project in the future. You may also lose the ability to use some of the CLI features and helpers.

Projects that do not use the CLI to generate scaffolds, or that deviate heavily from the proposed layout, may need to use the manual migration process, as automated migration tools might not work properly while the alpha update and AutoUpdate Plugin are designed to do a 3-way merge to keep your customizations intact.

For further information on the project layout, see What’s in a basic project?

Migration Options

Automated Updates via GitHub Actions

The AutoUpdate Plugin scaffolds an action that automatically monitors for new Kubebuilder releases and opens a GitHub Issue with a Pull Request compare link when updates are available. This is ideal for keeping your project up to date with minimal manual work.

This plugin provides a mechanism similar to Dependabot for GitHub, offering continuous updates with AI assistance for projects that follow the standard scaffold.

kubebuilder edit --plugins="autoupdate/v1-alpha"

See the AutoUpdate Plugin documentation for complete details.

Using Alpha Update Locally

If you prefer to run updates locally instead of relying on GitHub Actions, you can use the same logic as the AutoUpdate Plugin directly from your command line.

kubebuilder alpha update

This command uses the same underlying mechanism as the AutoUpdate Plugin. You can migrate your project, resolve any conflicts if needed, and then push a Pull Request from your local environment.

See the alpha update command reference for all options and flags.

Regenerate with Help and Merge Manually

The kubebuilder alpha generate command re-scaffolds your entire project based on your PROJECT file configuration. You can then manually compare and merge your custom code. For example, you can use it to regenerate your project after upgrading the Kubebuilder CLI version and then, manually use an IDE or git diff to compare and merge changes by hand into your existing codebase to ensure that all your changes are applied in a new scaffold.

This approach is useful for projects that heavily customize the scaffold or when other migration methods aren’t available. You might need to use this method only once to establish a baseline for future automated updates.

kubebuilder alpha generate

See the alpha generate command reference for details.

Fully Manual Migration

For complete control, you can manually migrate by creating a new project with the latest Kubebuilder version and porting your code over. This approach is more time-consuming but gives you full visibility into every change.

In this process, you will mainly run all commands from scratch to create a new project, APIs, controllers, webhooks, and other resources as needed. Then, you will manually copy your business logic and customizations from your old project to the new one.

See the Manual Migration Process Guide for a complete step-by-step walkthrough.