Viewing legacy documentation for Kubebuilder, check out the latest documentation instead.

go/v3 vs go/v4

This document covers all breaking changes when migrating from projects built using the plugin go/v3 (default for any scaffold done since 28 Apr 2021) to the next alpha version of the Golang plugin go/v4.

The details of all changes (breaking or otherwise) can be found in:

Common changes

  • go/v4 projects use Kustomize v5x (instead of v3x)
  • note that some manifests under config/ directory have been changed in order to no longer use the deprecated Kustomize features such as env vars.
  • A kustomization.yaml is scaffolded under config/samples. This helps simply and flexibly generate sample manifests: kustomize build config/samples.
  • adds support for Apple Silicon M1 (darwin/arm64)
  • remove support to CRD/WebHooks Kubernetes API v1beta1 version which are no longer supported since k8s 1.22
  • no longer scaffold webhook test files with "k8s.io/api/admission/v1beta1" the k8s API which is no longer served since k8s 1.25. By default webhooks test files are scaffolding using "k8s.io/api/admission/v1" which is support from k8s 1.20
  • no longer provide backwards compatible support with k8s versions < 1.16
  • change the layout to accommodate the community request to follow the Standard Go Project Layout by moving the api(s) under a new directory called api, controller(s) under a new directory called internal and the main.go under a new directory named cmd

TL;DR of the New go/v4 Plugin

More details on this can be found at here, but for the highlights, check below

Migrating to Kubebuilder go/v4

If you want to upgrade your scaffolding to use the latest and greatest features then, follow the guide which will cover the steps in the most straightforward way to allow you to upgrade your project to get all latest changes and improvements.

By updating the files manually

If you want to use the latest version of Kubebuilder CLI without changing your scaffolding then, check the following guide which will describe the steps to be performed manually to upgrade only your PROJECT version and start using the plugins versions.

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.