Black lives matter.

We stand in solidarity with the Black community.

Racism is unacceptable.

It conflicts with the core values of the Kubernetes project and our community does not tolerate it.

Migration from go/v3 to go/v4-alpha by updating the files manually

Make sure you understand the differences between Kubebuilder go/v3 and go/v4-alpha before continuing.

Please ensure you have followed the installation guide to install the required components.

The following guide describes the manual steps required to upgrade your PROJECT config file to begin using go/v4-alpha.

This way is more complex, susceptible to errors, and success cannot be assured. Also, by following these steps you will not get the improvements and bug fixes in the default generated project files.

Usually it is suggested to do it manually if you have customized your project and deviated too much from the proposed scaffold. Before continuing, ensure that you understand the note about [project customizations][project-customizations]. Note that you might need to spend more effort to do this process manually than to organize your project customizations. The proposed layout will keep your project maintainable and upgradable with less effort in the future.

The recommended upgrade approach is to follow the Migration Guide go/v3 to go/v4-alpha instead.

Migration from project config version “go/v3” to “go/v4”

Update PROJECT file layout which stores the information about the resources are use to enable plugins to make useful decisions when scaffolding.

Furthermore, the PROJECT file itself is now versioned. The version field corresponds to the version of the PROJECT file itself, while the layout field indicates the scaffolding and the primary plugin version in use.





Steps to migrate

  • Update the main.go with the changes which can be found in the samples under testdata for the release tag used. (see for example testdata/project-v4/main.go).
  • Update the Makefile with the changes which can be found in the samples under testdata for the release tag used. (see for example testdata/project-v4/Makefile)
  • Update the go.mod with the changes which can be found in the samples under testdata for the release tag used. (see for example testdata/project-v4/go.mod). Then, run go mod tidy to ensure that you get the latest dependencies and your Golang code has no breaking changes.
  • Update the manifest under config/ directory with all changes performed in the default scaffold done with go/v4-alpha plugin. (see for example testdata/project-v4/config/) to get all changes in the default scaffolds to be applied on your project
  • Create config/samples/kustomization.yaml with all CR samples specified. (see for example testdata/project-v4/config/samples/kustomization.yaml)
  • Replace the import admissionv1beta1 "" with admissionv1 "" in the webhook test files


In the steps above, you updated your project manually with the goal of ensuring that it follows the changes in the layout introduced with the go/v4-alpha plugin that update the scaffolds.

There is no option to verify that you properly updated the PROJECT file of your project. The best way to ensure that everything is updated correctly, would be to initialize a project using the go/v4-alpha plugin, (ie) using kubebuilder init --domain plugins=go/v4-alpha and generating the same API(s), controller(s), and webhook(s) in order to compare the generated configuration with the manually changed configuration.

Also, after all updates you would run the following commands:

  • make manifests (to re-generate the files using the latest version of the contrller-gen after you update the Makefile)
  • make all (to ensure that you are able to build and perform all operations)