Migrations

Upgrading your project scaffold to adopt the latest changes in Kubebuilder may involve migrating to a new plugin version (e.g., go.kubebuilder.io/v3 → go.kubebuilder.io/v4) or newer CLI toolchain. This process often includes re-scaffolding and manually merging your custom code.

This section details what’s required to migrate, between different versions of Kubebuilder scaffolding, as well as to more complex project layout structures.

The manual approach can be error-prone. That is why Kubebuilder introduces new alpha commands that help streamline the migration process.

Manual Migration

The traditional process involves:

  • Re-scaffolding the project using the latest Kubebuilder version or plugins

  • Re-adding custom logic manually

  • Running project generators:

    make generate
make manifests

Understanding the PROJECT File (Introduced in v3.0.0)

All inputs used by Kubebuilder are tracked in the PROJECT file. If you use the CLI to generate your scaffolds, this file will record the project’s configuration and metadata.

Alpha Migration Commands

Kubebuilder provides alpha commands to assist with project upgrades.

kubebuilder alpha generate

Re-scaffolds the project using the installed CLI version.

kubebuilder alpha generate

kubebuilder alpha update (available since v4.7.0)

Automates the migration by performing a 3-way merge:

  • Original scaffold
  • Your current customized version
  • Latest or specified target scaffold
kubebuilder alpha update

For more details, see the Alpha Command documentation.