From cb291c563909e7e6cb76ede97e92bcef1812e51d Mon Sep 17 00:00:00 2001 From: Camila Macedo <7708031+camilamacedo86@users.noreply.github.com> Date: Mon, 17 Nov 2025 00:23:46 +0000 Subject: [PATCH] (docs) Revamp migrations guides to reflect current tooling and options --- docs/book/src/SUMMARY.md | 15 +- docs/book/src/migration/legacy.md | 18 - .../legacy/manually_migration_guide_v2_v3.md | 727 ------------------ .../legacy/migration_guide_v1tov2.md | 219 ------ .../legacy/migration_guide_v2tov3.md | 155 ---- docs/book/src/migration/legacy/v1vsv2.md | 65 -- docs/book/src/migration/legacy/v2vsv3.md | 108 --- docs/book/src/migration/manual-process.md | 659 ++++++++++++++++ .../manually_migration_guide_gov3_to_gov4.md | 210 ----- .../migration/migration_guide_gov3_to_gov4.md | 161 ---- docs/book/src/migration/v3-plugins.md | 8 - docs/book/src/migration/v3vsv4.md | 75 -- docs/book/src/migrations.md | 152 ++-- 13 files changed, 766 insertions(+), 1806 deletions(-) delete mode 100644 docs/book/src/migration/legacy.md delete mode 100644 docs/book/src/migration/legacy/manually_migration_guide_v2_v3.md delete mode 100644 docs/book/src/migration/legacy/migration_guide_v1tov2.md delete mode 100644 docs/book/src/migration/legacy/migration_guide_v2tov3.md delete mode 100644 docs/book/src/migration/legacy/v1vsv2.md delete mode 100644 docs/book/src/migration/legacy/v2vsv3.md create mode 100644 docs/book/src/migration/manual-process.md delete mode 100644 docs/book/src/migration/manually_migration_guide_gov3_to_gov4.md delete mode 100644 docs/book/src/migration/migration_guide_gov3_to_gov4.md delete mode 100644 docs/book/src/migration/v3-plugins.md delete mode 100644 docs/book/src/migration/v3vsv4.md diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md index dfb3953d967..87ea5b72987 100644 --- a/docs/book/src/SUMMARY.md +++ b/docs/book/src/SUMMARY.md @@ -47,20 +47,7 @@ - [Migrations](./migrations.md) - - [Legacy (before <= v3.0.0)](./migration/legacy.md) - - [Kubebuilder v1 vs v2](migration/legacy/v1vsv2.md) - - - [Migration Guide](./migration/legacy/migration_guide_v1tov2.md) - - - [Kubebuilder v2 vs v3](migration/legacy/v2vsv3.md) - - - [Migration Guide](migration/legacy/migration_guide_v2tov3.md) - - [Migration by updating the files](migration/legacy/manually_migration_guide_v2_v3.md) - - [From v3.0.0 with plugins](./migration/v3-plugins.md) - - [go/v3 vs go/v4](migration/v3vsv4.md) - - - [Migration Guide](migration/migration_guide_gov3_to_gov4.md) - - [Migration by updating the files](migration/manually_migration_guide_gov3_to_gov4.md) + - [Manual Migration Process](./migration/manual-process.md) - [Single Group to Multi-Group](./migration/multi-group.md) - [Alpha Commands](./reference/alpha_commands.md) diff --git a/docs/book/src/migration/legacy.md b/docs/book/src/migration/legacy.md deleted file mode 100644 index da2ff198a66..00000000000 --- a/docs/book/src/migration/legacy.md +++ /dev/null @@ -1,18 +0,0 @@ -# Migration guides from Legacy versions < 3.0.0 - -Follow the migration guides from the legacy Kubebuilder versions up the required latest v3x version. -Note that from v3, a new ecosystem using plugins is introduced for better maintainability, reusability and user -experience . - -For more info, see the design docs of: - -- [Extensible CLI and Scaffolding Plugins: phase 1][plugins-phase1-design-doc] -- [Extensible CLI and Scaffolding Plugins: phase 1.5][plugins-phase1-design-doc-1.5] -- [Extensible CLI and Scaffolding Plugins - Phase 2][plugins-phase2-design-doc] - -Also, you can check the [Plugins section][plugins-section]. - -[plugins-phase1-design-doc]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/designs/extensible-cli-and-scaffolding-plugins-phase-1.md -[plugins-phase1-design-doc-1.5]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/designs/extensible-cli-and-scaffolding-plugins-phase-1-5.md -[plugins-phase2-design-doc]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/designs/extensible-cli-and-scaffolding-plugins-phase-2.md -[plugins-section]: ./../plugins/plugins.md diff --git a/docs/book/src/migration/legacy/manually_migration_guide_v2_v3.md b/docs/book/src/migration/legacy/manually_migration_guide_v2_v3.md deleted file mode 100644 index f8fc825e725..00000000000 --- a/docs/book/src/migration/legacy/manually_migration_guide_v2_v3.md +++ /dev/null @@ -1,727 +0,0 @@ -# Migration from v2 to v3 by updating the files manually - -Make sure you understand the [differences between Kubebuilder v2 and v3][migration-v2vsv3] -before continuing - -Please ensure you have followed the [installation guide](/quick-start.md#installation) -to install the required components. - -The following guide describes the manual steps required to upgrade your config version and start using the plugin-enabled version. - -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 you will only try to do it manually if you 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 organize your project customizations to follow up the proposed layout and keep your project maintainable and upgradable with less effort in the future. - -The recommended upgrade approach is to follow the [Migration Guide v2 to V3][migration-guide-v2-to-v3] instead. - -## Migration from project config version "2" to "3" - -Migrating between project configuration versions involves additions, removals, and/or changes -to fields in your project's `PROJECT` file, which is created by running the `init` command. - -The `PROJECT` file now has a new layout. It stores more information about what resources are in use, to better 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 - -The following steps describe the manual changes required to bring the project configuration file (`PROJECT`). These change will add the information that Kubebuilder would add when generating the file. This file can be found in the root directory. - -#### Add the `projectName` - -The project name is the name of the project directory in lowercase: - -```yaml -... -projectName: example -... -``` - -#### Add the `layout` - -The default plugin layout which is equivalent to the previous version is `go.kubebuilder.io/v2`: - -```yaml -... -layout: -- go.kubebuilder.io/v2 -... -``` - -#### Update the `version` - -The `version` field represents the version of project's layout. Update this to `"3"`: - -```yaml -... -version: "3" -... -``` - -#### Add the resource data - -The attribute `resources` represents the list of resources scaffolded in your project. - -You will need to add the following data for each resource added to the project. - -##### Add the Kubernetes API version by adding `resources[entry].api.crdVersion: v1beta1`: - -```yaml -... -resources: -- api: - ... - crdVersion: v1beta1 - domain: my.domain - group: webapp - kind: Guestbook - ... -``` - -##### Add the scope used do scaffold the CRDs by adding `resources[entry].api.namespaced: true` unless they were cluster-scoped: - -```yaml -... -resources: -- api: - ... - namespaced: true - group: webapp - kind: Guestbook - ... -``` - -##### If you have a controller scaffolded for the API then, add `resources[entry].controller: true`: - -```yaml -... -resources: -- api: - ... - controller: true - group: webapp - kind: Guestbook -``` - -##### Add the resource domain such as `resources[entry].domain: testproject.org` which usually will be the project domain unless the API scaffold is a core type and/or an external type: - -```yaml -... -resources: -- api: - ... - domain: testproject.org - group: webapp - kind: Guestbook -``` - - - -Note that you will only need to add the `domain` if your project has a scaffold for a core type API which the `Domain` value is not empty in Kubernetes API group qualified scheme definition. (For example, see [here](https://github.com/kubernetes/api/blob/v0.19.7/apps/v1/register.go#L26) that for Kinds from the API `apps` it has not a domain when see [here](https://github.com/kubernetes/api/blob/v0.19.7/authentication/v1/register.go#L26) that for Kinds from the API `authentication` its domain is `k8s.io` ) - - Check the following the list to know the core types supported and its domain: - -| Core Type | Domain | -|----------|:-------------:| -| admission | "k8s.io" | -| admissionregistration | "k8s.io" | -| apps | empty | -| auditregistration | "k8s.io" | -| apiextensions | "k8s.io" | -| authentication | "k8s.io" | -| authorization | "k8s.io" | -| autoscaling | empty | -| batch | empty | -| certificates | "k8s.io" | -| coordination | "k8s.io" | -| core | empty | -| events | "k8s.io" | -| extensions | empty | -| imagepolicy | "k8s.io" | -| networking | "k8s.io" | -| node | "k8s.io" | -| metrics | "k8s.io" | -| policy | empty | -| rbac.authorization | "k8s.io" | -| scheduling | "k8s.io" | -| setting | "k8s.io" | -| storage | "k8s.io" | - -Following an example where a controller was scaffold for the core type Kind Deployment via the command `create api --group apps --version v1 --kind Deployment --controller=true --resource=false --make=false`: - -```yaml -- controller: true - group: apps - kind: Deployment - path: k8s.io/api/apps/v1 - version: v1 -``` - -##### Add the `resources[entry].path` with the import path for the api: - - - -```yaml -... -resources: -- api: - ... - ... - group: webapp - kind: Guestbook - path: example/api/v1 -``` - -##### If your project is using webhooks then, add `resources[entry].webhooks.[type]: true` for each type generated and then, add `resources[entry].webhooks.webhookVersion: v1beta1`: - - - -```yaml -resources: -- api: - ... - ... - group: webapp - kind: Guestbook - webhooks: - defaulting: true - validation: true - webhookVersion: v1beta1 -``` - -#### Check your PROJECT file - -Now ensure that your `PROJECT` file has the same information when the manifests are generated via Kubebuilder V3 CLI. - -For the QuickStart example, the `PROJECT` file manually updated to use `go.kubebuilder.io/v2` would look like: - -```yaml -domain: my.domain -layout: -- go.kubebuilder.io/v2 -projectName: example -repo: example -resources: -- api: - crdVersion: v1 - namespaced: true - controller: true - domain: my.domain - group: webapp - kind: Guestbook - path: example/api/v1 - version: v1 -version: "3" -``` - -You can check the differences between the previous layout(`version 2`) and the current format(`version 3`) with the `go.kubebuilder.io/v2` by comparing an example scenario which involves more than one API and webhook, see: - -**Example (Project version 2)** - -```yaml -domain: testproject.org -repo: sigs.k8s.io/kubebuilder/example -resources: -- group: crew - kind: Captain - version: v1 -- group: crew - kind: FirstMate - version: v1 -- group: crew - kind: Admiral - version: v1 -version: "2" -``` - -**Example (Project version 3)** - -```yaml -domain: testproject.org -layout: -- go.kubebuilder.io/v2 -projectName: example -repo: sigs.k8s.io/kubebuilder/example -resources: -- api: - crdVersion: v1 - namespaced: true - controller: true - domain: testproject.org - group: crew - kind: Captain - path: example/api/v1 - version: v1 - webhooks: - defaulting: true - validation: true - webhookVersion: v1 -- api: - crdVersion: v1 - namespaced: true - controller: true - domain: testproject.org - group: crew - kind: FirstMate - path: example/api/v1 - version: v1 - webhooks: - conversion: true - webhookVersion: v1 -- api: - crdVersion: v1 - controller: true - domain: testproject.org - group: crew - kind: Admiral - path: example/api/v1 - plural: admirales - version: v1 - webhooks: - defaulting: true - webhookVersion: v1 -version: "3" -``` - -### Verification - -In the steps above, you updated only the `PROJECT` file which represents the project configuration. This configuration is useful only for the CLI tool. It should not affect how your project behaves. - -There is no option to verify that you properly updated the configuration file. The best way to ensure the configuration file has the correct `V3+` fields is to initialize a project with the same API(s), controller(s), and webhook(s) in order to compare generated configuration with the manually changed configuration. - -If you made mistakes in the above process, you will likely face issues using the CLI. - - -## Update your project to use go/v3 plugin - -Migrating between project [plugins][plugins-doc] involves additions, removals, and/or changes -to files created by any plugin-supported command, e.g. `init` and `create`. A plugin supports -one or more project config versions; make sure you upgrade your project's -config version to the latest supported by your target plugin version before upgrading plugin versions. - -The following steps describe the manual changes required to modify the project's layout enabling your project to use the `go/v3` plugin. These steps will not help you address all the bug fixes of the already generated scaffolds. - - - -### Steps to migrate - -#### Update your plugin version into the PROJECT file - -Before updating the `layout`, please ensure you have followed the above steps to upgrade your Project version to `3`. Once you have upgraded the project version, update the `layout` to the new plugin version ` go.kubebuilder.io/v3` as follows: - -```yaml -domain: my.domain -layout: -- go.kubebuilder.io/v3 -... -``` - -#### Upgrade the Go version and its dependencies: - -Ensure that your `go.mod` is using Go version `1.15` and the following dependency versions: - -```go -module example - -go 1.18 - -require ( - github.com/onsi/ginkgo/v2 v2.1.4 - github.com/onsi/gomega v1.19.0 - k8s.io/api v0.24.0 - k8s.io/apimachinery v0.24.0 - k8s.io/client-go v0.24.0 - sigs.k8s.io/controller-runtime v0.12.1 -) - -``` - -#### Update the golang image - -In the Dockerfile, replace: - -``` -# Build the manager binary -FROM docker.io/golang:1.13 as builder -``` - -With: -``` -# Build the manager binary -FROM docker.io/golang:1.16 as builder -``` - -#### Update your Makefile - -##### To allow controller-gen to scaffold the nw Kubernetes APIs - -To allow `controller-gen` and the scaffolding tool to use the new API versions, replace: - -``` -CRD_OPTIONS ?= "crd:trivialVersions=true" -``` - -With: - -``` -CRD_OPTIONS ?= "crd" -``` - -##### To allow automatic downloads - -To allow downloading the newer versions of the Kubernetes binaries required by Envtest into the `testbin/` directory of your project instead of the global setup, replace: - -```makefile -# Run tests -test: generate fmt vet manifests - go test ./... -coverprofile cover.out -``` - -With: - -```makefile -# Setting SHELL to bash allows bash commands to be executed by recipes. -# Options are set to exit when a recipe line exits non-zero or a piped command fails. -SHELL = /usr/bin/env bash -o pipefail -.SHELLFLAGS = -ec - -ENVTEST_ASSETS_DIR=$(shell pwd)/testbin -test: manifests generate fmt vet ## Run tests. - mkdir -p ${ENVTEST_ASSETS_DIR} - test -f ${ENVTEST_ASSETS_DIR}/setup-envtest.sh || curl -sSLo ${ENVTEST_ASSETS_DIR}/setup-envtest.sh https://raw.githubusercontent.com/kubernetes-sigs/controller-runtime/v0.8.3/hack/setup-envtest.sh - source ${ENVTEST_ASSETS_DIR}/setup-envtest.sh; fetch_envtest_tools $(ENVTEST_ASSETS_DIR); setup_envtest_env $(ENVTEST_ASSETS_DIR); go test ./... -coverprofile cover.out -``` - - - -##### To upgrade `controller-gen` and `kustomize` dependencies versions used - -To upgrade the `controller-gen` and `kustomize` version used to generate the manifests replace: - -``` -# find or download controller-gen -# download controller-gen if necessary -controller-gen: -ifeq (, $(shell which controller-gen)) - @{ \ - set -e ;\ - CONTROLLER_GEN_TMP_DIR=$$(mktemp -d) ;\ - cd $$CONTROLLER_GEN_TMP_DIR ;\ - go mod init tmp ;\ - go get sigs.k8s.io/controller-tools/cmd/controller-gen@v0.2.5 ;\ - rm -rf $$CONTROLLER_GEN_TMP_DIR ;\ - } -CONTROLLER_GEN=$(GOBIN)/controller-gen -else -CONTROLLER_GEN=$(shell which controller-gen) -endif -``` - -With: - -``` -##@ Build Dependencies - -## Location to install dependencies to -LOCALBIN ?= $(shell pwd)/bin -$(LOCALBIN): - mkdir -p $(LOCALBIN) - -## Tool Binaries -KUSTOMIZE ?= $(LOCALBIN)/kustomize -CONTROLLER_GEN ?= $(LOCALBIN)/controller-gen -ENVTEST ?= $(LOCALBIN)/setup-envtest - -## Tool Versions -KUSTOMIZE_VERSION ?= v3.8.7 -CONTROLLER_TOOLS_VERSION ?= v0.9.0 - -KUSTOMIZE_INSTALL_SCRIPT ?= "https://raw.githubusercontent.com/kubernetes-sigs/kustomize/master/hack/install_kustomize.sh" -.PHONY: kustomize -kustomize: $(KUSTOMIZE) ## Download kustomize locally if necessary. -$(KUSTOMIZE): $(LOCALBIN) - test -s $(LOCALBIN)/kustomize || { curl -Ss $(KUSTOMIZE_INSTALL_SCRIPT) | bash -s -- $(subst v,,$(KUSTOMIZE_VERSION)) $(LOCALBIN); } - -.PHONY: controller-gen -controller-gen: $(CONTROLLER_GEN) ## Download controller-gen locally if necessary. -$(CONTROLLER_GEN): $(LOCALBIN) - test -s $(LOCALBIN)/controller-gen || GOBIN=$(LOCALBIN) go install sigs.k8s.io/controller-tools/cmd/controller-gen@$(CONTROLLER_TOOLS_VERSION) - -.PHONY: envtest -envtest: $(ENVTEST) ## Download envtest-setup locally if necessary. -$(ENVTEST): $(LOCALBIN) - test -s $(LOCALBIN)/setup-envtest || GOBIN=$(LOCALBIN) go install sigs.k8s.io/controller-runtime/tools/setup-envtest@latest -``` - -And then, to make your project use the `kustomize` version defined in the Makefile, replace all usage of `kustomize` with `$(KUSTOMIZE)` - - - -#### Update your controllers - - - -Replace: - -```go -func (r *Reconciler) Reconcile(req ctrl.Request) (ctrl.Result, error) { - ctx := context.Background() - log := r.Log.WithValues("cronjob", req.NamespacedName) -``` - -With: - -```go -func (r *Reconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) { - log := r.Log.WithValues("cronjob", req.NamespacedName) -``` - -#### Update your controller and webhook test suite - - - -Replace: - -```go - . "github.com/onsi/ginkgo" -``` - -With: - -```go - . "github.com/onsi/ginkgo/v2" -``` - -Also, adjust your test suite. - -For Controller Suite: - -```go - RunSpecsWithDefaultAndCustomReporters(t, - "Controller Suite", - []Reporter{printer.NewlineReporter{}}) -``` - -With: - -```go - RunSpecs(t, "Controller Suite") -``` - -For Webhook Suite: - -```go - RunSpecsWithDefaultAndCustomReporters(t, - "Webhook Suite", - []Reporter{printer.NewlineReporter{}}) -``` - -With: - -```go - RunSpecs(t, "Webhook Suite") -``` - -Last but not least, remove the timeout variable from the `BeforeSuite` blocks: - -Replace: - -```go -var _ = BeforeSuite(func(done Done) { - .... -}, 60) -``` - -With - - -```go -var _ = BeforeSuite(func(done Done) { - .... -}) -``` - - - -#### Change Logger to use flag options - -In the `main.go` file replace: - -```go -flag.Parse() - -ctrl.SetLogger(zap.New(zap.UseDevMode(true))) -``` - -With: - -```go -opts := zap.Options{ - Development: true, -} -opts.BindFlags(flag.CommandLine) -flag.Parse() - -ctrl.SetLogger(zap.New(zap.UseFlagOptions(&opts))) -``` - -#### Rename the manager flags - -The manager flags `--metrics-addr` and `enable-leader-election` were renamed to `--metrics-bind-address` and `--leader-elect` to be more aligned with core Kubernetes Components. More info: [#1839][issue-1893]. - -In your `main.go` file replace: - - -```go -func main() { - var metricsAddr string - var enableLeaderElection bool - flag.StringVar(&metricsAddr, "metrics-addr", ":8080", "The address the metric endpoint binds to.") - flag.BoolVar(&enableLeaderElection, "enable-leader-election", false, - "Enable leader election for controller manager. "+ - "Enabling this will ensure there is only one active controller manager.") -``` - -With: - -```go -func main() { - var metricsAddr string - var enableLeaderElection bool - flag.StringVar(&metricsAddr, "metrics-bind-address", ":8080", "The address the metric endpoint binds to.") - flag.BoolVar(&enableLeaderElection, "leader-elect", false, - "Enable leader election for controller manager. "+ - "Enabling this will ensure there is only one active controller manager.") -``` - -And then, rename the flags in the `config/default/manager_auth_proxy_patch.yaml` and `config/default/manager.yaml`: - -```yaml -- name: manager -args: -- "--health-probe-bind-address=:8081" -- "--metrics-bind-address=127.0.0.1:8080" -- "--leader-elect" -``` - -#### Verification - -Finally, we can run `make` and `make docker-build` to ensure things are working -fine. - -## Change your project to remove the Kubernetes deprecated API versions usage - - - - -The following steps describe a workflow to upgrade your project to remove the deprecated Kubernetes APIs: `apiextensions.k8s.io/v1beta1`, `admissionregistration.k8s.io/v1beta1`, `cert-manager.io/v1alpha2`. - -The Kubebuilder CLI tool does not support scaffolded resources for both Kubernetes API versions such as; an API/CRD with `apiextensions.k8s.io/v1beta1` and another one with `apiextensions.k8s.io/v1`. - - - -The first step is to update your `PROJECT` file by replacing the `api.crdVersion:v1beta` and `webhooks.WebhookVersion:v1beta` with `api.crdVersion:v1` and `webhooks.WebhookVersion:v1` which would look like: - -```yaml -domain: my.domain -layout: go.kubebuilder.io/v3 -projectName: example -repo: example -resources: -- api: - crdVersion: v1 - namespaced: true - group: webapp - kind: Guestbook - version: v1 - webhooks: - defaulting: true - webhookVersion: v1 -version: "3" -``` - -You can try to re-create the APIS(CRDs) and Webhooks manifests by using the `--force` flag. - - - -Now, re-create the APIS(CRDs) and Webhooks manifests by running the `kubebuilder create api` and `kubebuilder create webhook` for the same group, kind and versions with the flag `--force`, respectively. - - -[migration-guide-v2-to-v3]: migration_guide_v2tov3.md -[envtest]: https://book.kubebuilder.io/reference/testing/envtest.html -[controller-releases]: https://github.com/kubernetes-sigs/controller-runtime/releases -[issue-1893]: https://github.com/kubernetes-sigs/kubebuilder/issues/1839 -[plugins-doc]: /reference/cli-plugins.md -[migration-v2vsv3]: v2vsv3.md -[custom-resource-definition-versioning]: https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning/ -[issue-1999]: https://github.com/kubernetes-sigs/kubebuilder/issues/1999 -[project-customizations]: v2vsv3.md#project-customizations -[doc-envtest]:/reference/envtest.md diff --git a/docs/book/src/migration/legacy/migration_guide_v1tov2.md b/docs/book/src/migration/legacy/migration_guide_v1tov2.md deleted file mode 100644 index 3080ceb6c42..00000000000 --- a/docs/book/src/migration/legacy/migration_guide_v1tov2.md +++ /dev/null @@ -1,219 +0,0 @@ -# Migration from v1 to v2 - -Make sure you understand the [differences between Kubebuilder v1 and v2](./v1vsv2.md) -before continuing - -Please ensure you have followed the [installation guide](/quick-start.md#installation) -to install the required components. - -The recommended way to migrate a v1 project is to create a new v2 project and -copy over the API and the reconciliation code. The conversion will end up with a -project that looks like a native v2 project. However, in some cases, it's -possible to do an in-place upgrade (i.e. reuse the v1 project layout, upgrading -controller-runtime and controller-tools. - -Let's take as example an V1 project and migrate it to Kubebuilder -v2. At the end, we should have something that looks like the -[example v2 project][v2-project]. - -## Preparation - -We'll need to figure out what the group, version, kind and domain are. - -Let's take a look at our current v1 project structure: - -``` -pkg/ -├── apis -│   ├── addtoscheme_batch_v1.go -│   ├── apis.go -│   └── batch -│   ├── group.go -│   └── v1 -│   ├── cronjob_types.go -│   ├── cronjob_types_test.go -│   ├── doc.go -│   ├── register.go -│   ├── v1_suite_test.go -│   └── zz_generated.deepcopy.go -├── controller -└── webhook -``` - -All of our API information is stored in `pkg/apis/batch`, so we can look -there to find what we need to know. - -In `cronjob_types.go`, we can find - -```go -type CronJob struct {...} -``` - -In `register.go`, we can find - -```go -SchemeGroupVersion = schema.GroupVersion{Group: "batch.tutorial.kubebuilder.io", Version: "v1"} -``` - -Putting that together, we get `CronJob` as the kind, and `batch.tutorial.kubebuilder.io/v1` as the group-version - -## Initialize a v2 Project - -Now, we need to initialize a v2 project. Before we do that, though, we'll need -to initialize a new go module if we're not on the `gopath`: - -```bash -go mod init tutorial.kubebuilder.io/project -``` - -Then, we can finish initializing the project with kubebuilder: - -```bash -kubebuilder init --domain tutorial.kubebuilder.io -``` - -## Migrate APIs and Controllers - -Next, we'll re-scaffold out the API types and controllers. Since we want both, -we'll say yes to both the API and controller prompts when asked what parts we -want to scaffold: - -```bash -kubebuilder create api --group batch --version v1 --kind CronJob -``` - -If you're using multiple groups, some manual work is required to migrate. -Please follow [this](/migration/multi-group.md) for more details. - -### Migrate the APIs - -Now, let's copy the API definition from `pkg/apis/batch/v1/cronjob_types.go` to -`api/v1/cronjob_types.go`. We only need to copy the implementation of the `Spec` -and `Status` fields. - -We can replace the `+k8s:deepcopy-gen:interfaces=...` marker (which is -[deprecated in kubebuilder](/reference/markers/object.md)) with -`+kubebuilder:object:root=true`. - -We don't need the following markers any more (they're not used anymore, and are -relics from much older versions of Kubebuilder): - -```go -// +genclient -// +k8s:openapi-gen=true -``` - -Our API types should look like the following: - -```go -// +kubebuilder:object:root=true -// +kubebuilder:subresource:status -// CronJob is the Schema for the cronjobs API -type CronJob struct {...} - -// +kubebuilder:object:root=true - -// CronJobList contains a list of CronJob -type CronJobList struct {...} -``` - -### Migrate the Controllers - -Now, let's migrate the controller reconciler code from -`pkg/controller/cronjob/cronjob_controller.go` to -`controllers/cronjob_controller.go`. - -We'll need to copy -- the fields from the `ReconcileCronJob` struct to `CronJobReconciler` -- the contents of the `Reconcile` function -- the [rbac related markers](/reference/markers/rbac.md) to the new file. -- the code under `func add(mgr manager.Manager, r reconcile.Reconciler) error` -to `func SetupWithManager` - -## Migrate the Webhooks - -If you don't have a webhook, you can skip this section. - -### Webhooks for Core Types and External CRDs - -If you are using webhooks for Kubernetes core types (e.g. Pods), or for an -external CRD that is not owned by you, you can refer the -[controller-runtime example for builtin types][builtin-type-example] -and do something similar. Kubebuilder doesn't scaffold much for these cases, but -you can use the library in controller-runtime. - -### Scaffold Webhooks for our CRDs - -Now let's scaffold the webhooks for our CRD (CronJob). We'll need to run the -following command with the `--defaulting` and `--programmatic-validation` flags -(since our test project uses defaulting and validating webhooks): - -```bash -kubebuilder create webhook --group batch --version v1 --kind CronJob --defaulting --programmatic-validation -``` - -Depending on how many CRDs need webhooks, we may need to run the above command -multiple times with different Group-Version-Kinds. - -Now, we'll need to copy the logic for each webhook. For validating webhooks, we -can copy the contents from -`func validatingCronJobFn` in `pkg/default_server/cronjob/validating/cronjob_create_handler.go` -to `func ValidateCreate` in `api/v1/cronjob_webhook.go` and then the same for `update`. - -Similarly, we'll copy from `func mutatingCronJobFn` to `func Default`. - -### Webhook Markers - -When scaffolding webhooks, Kubebuilder v2 adds the following markers: - -``` -// These are v2 markers - -// This is for the mutating webhook -// +kubebuilder:webhook:path=/mutate-batch-tutorial-kubebuilder-io-v1-cronjob,mutating=true,failurePolicy=fail,groups=batch.tutorial.kubebuilder.io,resources=cronjobs,verbs=create;update,versions=v1,name=mcronjob.kb.io - -... - -// This is for the validating webhook -// +kubebuilder:webhook:path=/validate-batch-tutorial-kubebuilder-io-v1-cronjob,mutating=false,failurePolicy=fail,groups=batch.tutorial.kubebuilder.io,resources=cronjobs,verbs=create;update,versions=v1,name=vcronjob.kb.io -``` - -The default verbs are `verbs=create;update`. We need to ensure `verbs` matches -what we need. For example, if we only want to validate creation, then we would -change it to `verbs=create`. - -We also need to ensure `failure-policy` is still the same. - -Markers like the following are no longer needed (since they deal with -self-deploying certificate configuration, which was removed in v2): - -```go -// v1 markers -// +kubebuilder:webhook:port=9876,cert-dir=/tmp/cert -// +kubebuilder:webhook:service=test-system:webhook-service,selector=app:webhook-server -// +kubebuilder:webhook:secret=test-system:webhook-server-secret -// +kubebuilder:webhook:mutating-webhook-config-name=test-mutating-webhook-cfg -// +kubebuilder:webhook:validating-webhook-config-name=test-validating-webhook-cfg -``` - -In v1, a single webhook marker may be split into multiple ones in the same -paragraph. In v2, each webhook must be represented by a single marker. - -## Others - -If there are any manual updates in `main.go` in v1, we need to port the changes -to the new `main.go`. We'll also need to ensure all of the needed schemes have -been registered. - -If there are additional manifests added under `config` directory, port them as -well. - -Change the image name in the Makefile if needed. - -## Verification - -Finally, we can run `make` and `make docker-build` to ensure things are working -fine. - -[v2-project]: https://github.com/kubernetes-sigs/kubebuilder/tree/master/docs/book/src/cronjob-tutorial/testdata/project -[builtin-type-example]: https://sigs.k8s.io/controller-runtime/examples/builtins diff --git a/docs/book/src/migration/legacy/migration_guide_v2tov3.md b/docs/book/src/migration/legacy/migration_guide_v2tov3.md deleted file mode 100644 index 420e20dc8fe..00000000000 --- a/docs/book/src/migration/legacy/migration_guide_v2tov3.md +++ /dev/null @@ -1,155 +0,0 @@ -# Migration from v2 to v3 - -Make sure you understand the [differences between Kubebuilder v2 and v3][v2vsv3] -before continuing. - -Please ensure you have followed the [installation guide][quick-start] -to install the required components. - -The recommended way to migrate a v2 project is to create a new v3 project and -copy over the API and the reconciliation code. The conversion will end up with a -project that looks like a native v3 project. However, in some cases, it's -possible to do an in-place upgrade (i.e. reuse the v2 project layout, upgrading -[controller-runtime][controller-runtime] and [controller-tools][controller-tools]). - -## Initialize a v3 Project - - - -Create a new directory with the name of your project. Note that -this name is used in the scaffolds to create the name of your manager Pod and of the Namespace where the Manager is deployed by default. - -```bash -$ mkdir migration-project-name -$ cd migration-project-name -``` - -Now, we need to initialize a v3 project. Before we do that, though, we'll need -to initialize a new go module if we're not on the `GOPATH`. While technically this is -not needed inside `GOPATH`, it is still recommended. - -```bash -go mod init tutorial.kubebuilder.io/migration-project -``` - - - -Then, we can finish initializing the project with kubebuilder. - -```bash -kubebuilder init --domain tutorial.kubebuilder.io -``` - - - -## Migrate APIs and Controllers - -Next, we'll re-scaffold out the API types and controllers. - - - -```bash -kubebuilder create api --group batch --version v1 --kind CronJob -``` - -### Migrate the APIs - - - -Now, let's copy the API definition from `api/v1/_types.go` in our old project to the new one. - -These files have not been modified by the new plugin, so you should be able to replace your freshly scaffolded files by your old one. There may be some cosmetic changes. So you can choose to only copy the types themselves. - -### Migrate the Controllers - -Now, let's migrate the controller code from `controllers/cronjob_controller.go` in our old project to the new one. There is a breaking change and there may be some cosmetic changes. - -The new `Reconcile` method receives the context as an argument now, instead of having to create it with `context.Background()`. You can copy the rest of the code in your old controller to the scaffolded methods replacing: - -```go -func (r *CronJobReconciler) Reconcile(req ctrl.Request) (ctrl.Result, error) { - ctx := context.Background() - log := r.Log.WithValues("cronjob", req.NamespacedName) -``` - -With: - -```go -func (r *CronJobReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) { - log := r.Log.WithValues("cronjob", req.NamespacedName) -``` - - - -## Migrate the Webhooks - - - -Now let's scaffold the webhooks for our CRD (CronJob). We'll need to run the -following command with the `--defaulting` and `--programmatic-validation` flags -(since our test project uses defaulting and validating webhooks): - -```bash -kubebuilder create webhook --group batch --version v1 --kind CronJob --defaulting --programmatic-validation -``` - -Now, let's copy the webhook definition from `api/v1/_webhook.go` from our old project to the new one. - -## Others - -If there are any manual updates in `main.go` in v2, we need to port the changes to the new `main.go`. We’ll also need to ensure all of the needed schemes have been registered. - -If there are additional manifests added under config directory, port them as well. - -Change the image name in the Makefile if needed. - -## Verification - -Finally, we can run `make` and `make docker-build` to ensure things are working -fine. - -[v2vsv3]: v2vsv3.md -[quick-start]: /quick-start.md#installation -[controller-tools]: https://github.com/kubernetes-sigs/controller-tools/releases -[controller-runtime]: https://github.com/kubernetes-sigs/controller-runtime/releases -[multi-group]: /migration/multi-group.md \ No newline at end of file diff --git a/docs/book/src/migration/legacy/v1vsv2.md b/docs/book/src/migration/legacy/v1vsv2.md deleted file mode 100644 index 993a29845a3..00000000000 --- a/docs/book/src/migration/legacy/v1vsv2.md +++ /dev/null @@ -1,65 +0,0 @@ -# Kubebuilder v1 vs v2 (Legacy v1.0.0+ to v2.0.0 Kubebuilder CLI versions) - -This document cover all breaking changes when migrating from v1 to v2. - -The details of all changes (breaking or otherwise) can be found in -[controller-runtime](https://github.com/kubernetes-sigs/controller-runtime/releases), -[controller-tools](https://github.com/kubernetes-sigs/controller-tools/releases) -and [kubebuilder](https://github.com/kubernetes-sigs/kubebuilder/releases) -release notes. - -## Common changes - -V2 project uses go modules. But kubebuilder will continue to support `dep` until -go 1.13 is out. - -## controller-runtime - -- `Client.List` now uses functional options (`List(ctx, list, ...option)`) instead -of `List(ctx, ListOptions, list)`. -- `Client.DeleteAllOf` was added to the `Client` interface. - -- Metrics are on by default now. - -- A number of packages under `pkg/runtime` have been moved, with their old -locations deprecated. The old locations will be removed before -controller-runtime v1.0.0. See the [godocs][pkg-runtime-godoc] for more -information. - -#### Webhook-related - -- Automatic certificate generation for webhooks has been removed, and webhooks -will no longer self-register. Use controller-tools to generate a webhook -configuration. If you need certificate generation, we recommend using -[cert-manager](https://github.com/cert-manager/cert-manager). Kubebuilder v2 will -scaffold out cert manager configs for you to use -- see the -[Webhook Tutorial](/cronjob-tutorial/webhook-implementation.md) for more details. - -- The `builder` package now has separate builders for controllers and webhooks, -which facilitates choosing which to run. - -## controller-tools - -The generator framework has been rewritten in v2. It still works the same as -before in many cases, but be aware that there are some breaking changes. -Please check [marker documentation](/reference/markers.md) for more details. - -## Kubebuilder - -- Kubebuilder v2 introduces a simplified project layout. You can find the design -doc [here](https://github.com/kubernetes-sigs/kubebuilder/blob/master/designs/simplified-scaffolding.md). - -- In v1, the manager is deployed as a `StatefulSet`, while it's deployed as a -`Deployment` in v2. - -- The `kubebuilder create webhook` command was added to scaffold -mutating/validating/conversion webhooks. It replaces the -`kubebuilder alpha webhook` command. - -- v2 uses `distroless/static` instead of Ubuntu as base image. This reduces -image size and attack surface. - -- v2 requires kustomize v3.1.0+. - -[LeaderElectionRunable]: https://pkg.go.dev/sigs.k8s.io/controller-runtime/pkg/manager?tab=doc#LeaderElectionRunnable -[pkg-runtime-godoc]: https://pkg.go.dev/sigs.k8s.io/controller-runtime/pkg/runtime?tab=doc diff --git a/docs/book/src/migration/legacy/v2vsv3.md b/docs/book/src/migration/legacy/v2vsv3.md deleted file mode 100644 index 2c606b35ed5..00000000000 --- a/docs/book/src/migration/legacy/v2vsv3.md +++ /dev/null @@ -1,108 +0,0 @@ -# Kubebuilder v2 vs v3 (Legacy Kubebuilder v2.0.0+ layout to 3.0.0+) - -This document covers all breaking changes when migrating from v2 to v3. - -The details of all changes (breaking or otherwise) can be found in -[controller-runtime][controller-runtime], -[controller-tools][controller-tools] -and [kb-releases][kb-releases] release notes. - -## Common changes - -v3 projects use Go modules and request Go 1.18+. Dep is no longer supported for dependency management. - -## Kubebuilder - -- Preliminary support for plugins was added. For more info see the [Extensible CLI and Scaffolding Plugins: phase 1][plugins-phase1-design-doc], - the [Extensible CLI and Scaffolding Plugins: phase 1.5][plugins-phase1-design-doc-1.5] and the [Extensible CLI and Scaffolding Plugins - Phase 2][plugins-phase2-design-doc] - design docs. Also, you can check the [Plugins section][plugins-section]. - -- The `PROJECT` file now has a new layout. It stores more information about what resources are in use, to better 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 & primary plugin version in use. - -- The version of the image `gcr.io/kubebuilder/kube-rbac-proxy`, which is an optional component enabled by default to secure the request made against the manager, was updated from `0.5.0` to `0.11.0` to address security concerns. The details of all changes can be found in [kube-rbac-proxy][kube-rbac-proxy]. - -## TL;DR of the New `go/v3` Plugin - -***More details on this can be found at [here][kb-releases], but for the highlights, check below*** - - - -- Scaffolded/Generated API version changes: - * Use `apiextensions/v1` for generated CRDs (`apiextensions/v1beta1` was deprecated in Kubernetes `1.16`) - * Use `admissionregistration.k8s.io/v1` for generated webhooks (`admissionregistration.k8s.io/v1beta1` was deprecated in Kubernetes `1.16`) - * Use `cert-manager.io/v1` for the certificate manager when webhooks are used (`cert-manager.io/v1alpha2` was deprecated in `Cert-Manager 0.14`. More info: [CertManager v1.0 docs][cert-manager-docs]) - -- Code changes: - * The manager flags `--metrics-addr` and `enable-leader-election` now are named `--metrics-bind-address` and `--leader-elect` to be more aligned with core Kubernetes Components. More info: [#1839][issue-1893] - * Liveness and Readiness probes are now added by default using [`healthz.Ping`][healthz-ping]. - * A new option to create the projects using ComponentConfig is introduced. For more info see its [enhancement proposal][enhancement proposal] and the [Component config tutorial][component-config-tutorial] - * Manager manifests now use `SecurityContext` to address security concerns. More info: [#1637][issue-1637] -- Misc: - * Support for [controller-tools][controller-tools] `v0.9.0` (for `go/v2` it is `v0.3.0` and previously it was `v0.2.5`) - * Support for [controller-runtime][controller-runtime] `v0.12.1` (for `go/v2` it is `v0.6.4` and previously it was `v0.5.0`) - * Support for [kustomize][kustomize] `v3.8.7` (for `go/v2` it is `v3.5.4` and previously it was `v3.1.0`) - * Required Envtest binaries are automatically downloaded - * The minimum Go version is now `1.18` (previously it was `1.13`). - - - -## Migrating to Kubebuilder v3 - -So you want to upgrade your scaffolding to use the latest and greatest features then, follow up the following 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. - - - -- [Migration Guide v2 to V3][migration-guide-v2-to-v3] **(Recommended)** - -### By updating the files manually - -So you want to use the latest version of Kubebuilder CLI without changing your scaffolding then, check the following guide which will describe the manually steps required for you to upgrade only your PROJECT version and starts to use 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. - -You will check that you can still using the previous layout by using the `go/v2` plugin which will not upgrade the [controller-runtime][controller-runtime] and [controller-tools][controller-tools] to the latest version used with `go/v3` becuase of its breaking changes. By checking this guide you know also how to manually change the files to use the `go/v3` plugin and its dependencies versions. - -- [Migrating to Kubebuilder v3 by updating the files manually][manually-upgrade] - -[plugins-phase1-design-doc]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/designs/extensible-cli-and-scaffolding-plugins-phase-1.md -[plugins-phase1-design-doc-1.5]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/designs/extensible-cli-and-scaffolding-plugins-phase-1-5.md -[plugins-phase2-design-doc]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/designs/extensible-cli-and-scaffolding-plugins-phase-2.md -[plugins-section]: ./../../plugins/plugins.md -[manually-upgrade]: manually_migration_guide_v2_v3.md -[component-config-tutorial]: ../../component-config-tutorial/tutorial.md -[issue-1893]: https://github.com/kubernetes-sigs/kubebuilder/issues/1839 -[migration-guide-v2-to-v3]: migration_guide_v2tov3.md -[healthz-ping]: https://pkg.go.dev/sigs.k8s.io/controller-runtime/pkg/healthz#CheckHandler -[controller-runtime]: https://github.com/kubernetes-sigs/controller-runtime/releases -[controller-tools]: https://github.com/kubernetes-sigs/controller-tools/releases -[kustomize]: https://github.com/kubernetes-sigs/kustomize/releases -[issue-1637]: https://github.com/kubernetes-sigs/kubebuilder/issues/1637 -[enhancement proposal]: https://github.com/kubernetes/enhancements/tree/master/keps/sig-cluster-lifecycle/wgs -[cert-manager-docs]: https://cert-manager.io/docs/installation/upgrading/ -[kb-releases]: https://github.com/kubernetes-sigs/kubebuilder/releases -[kube-rbac-proxy]: https://github.com/brancz/kube-rbac-proxy/releases -[basic-project-doc]: ../../cronjob-tutorial/basic-project.md -[kustomize]: https://github.com/kubernetes-sigs/kustomize diff --git a/docs/book/src/migration/manual-process.md b/docs/book/src/migration/manual-process.md new file mode 100644 index 00000000000..6d289f3d980 --- /dev/null +++ b/docs/book/src/migration/manual-process.md @@ -0,0 +1,659 @@ +# Manual Migration Process + +Please ensure you have followed the [installation guide][quick-start] +to install the required components and have the desired version of the +Kubebuilder CLI available in your `PATH`. + +This guide outlines the manual steps to migrate your existing Kubebuilder +project to a newer version of the Kubebuilder framework. This process involves +re-scaffolding your project and manually porting over your custom code and configurations. + + + +From Kubebuilder `v3.0.0` onwards, all inputs used by Kubebuilder are tracked in the [PROJECT][project-config] file. +Ensure that you check this file in your current project to verify the recorded configuration and metadata. +Review the [PROJECT file documentation][project-config] for a better understanding. + +Also, before starting, it is recommended to check [What's in a basic project?][basic-project-doc] +to better understand the project layouts and structure. + + +## Step 1: Prepare Your Current Project + +Before starting the migration, you need to backup your work and identify key project information. + +### 1.1 Create a backup branch + +Create a branch from your current codebase to preserve your work: + +```bash +git checkout -b migration +``` + + + +### 1.2 Create a backup + +Create a directory to hold all your current project files as a backup: + +```bash +mkdir ../migration-backup +cp -r . ../migration-backup/ +``` + +### 1.3 Clean your project directory + +Remove all files except `.git` from your current project directory to start fresh: + +```bash +find . -not -path './.git*' -not -name '.' -not -name '..' -delete +``` + +## Step 2: Initialize the New Project + +You have two options: use `alpha generate` if your project has a `PROJECT` file, or manually initialize. + + + +### Option B: Manual Initialization + +If `alpha generate` doesn't work or you prefer manual control, follow these steps: + +### 2.1 Identify your module and domain + +First, identify the information you'll need for initialization. You can compare with your main branch or check the backup directory. + +**Module path** - Check your `go.mod` file: + +```bash +# Compare with main branch +git show main:go.mod +``` + +Look for the module line: + +```go +module tutorial.kubebuilder.io/migration-project +``` + +**Domain** - Check your `PROJECT` file (if it exists): + +```bash +# Compare with main branch +git show main:PROJECT +``` + +Look for the domain line: + +```yaml +domain: tutorial.kubebuilder.io +``` + + + +If you don't have a `PROJECT` file (versions < `v3.0.0`), check your CRD files under `config/crd/bases/` or examine the API group names. The domain is the part after the group name in your API groups. + +### 2.2 Initialize the Go module + +Initialize a new Go module using the same module path from your original project: + +```bash +go mod init tutorial.kubebuilder.io/migration-project +``` + +Replace `tutorial.kubebuilder.io/migration-project` with your actual module path. + +### 2.3 Initialize Kubebuilder project + +Initialize the project with Kubebuilder: + +```bash +kubebuilder init --domain tutorial.kubebuilder.io --repo tutorial.kubebuilder.io/migration-project +``` + +Replace with your actual domain and repository (module path). + + + +### 2.4 Enable multi-group support (if needed) + +**Multi-group** projects organize APIs into different groups, with each group in its own directory. +This is useful when you have APIs for different purposes or domains. + +**Check if your project uses multi-group layout** by examining your backup's directory structure: + +- **Single-group layout:** All APIs in one group + - `api/v1/cronjob_types.go` + - `api/v1/job_types.go` + - `api/v2/cronjob_types.go` + +- **Multi-group layout:** APIs organized by group + - `api/batch/v1/cronjob_types.go` + - `api/crew/v1/captain_types.go` + - `api/sea/v1/ship_types.go` + +You can also check your backup's `PROJECT` file for: + +```yaml +multigroup: true +``` + +**If your project uses multi-group layout**, enable it before creating APIs: + +```bash +kubebuilder edit --multigroup=true +``` + + + +When following this guide for any to latest migration, you'll naturally get the new layout since you're creating +a fresh v4 project and porting your code into it. + +## Step 3: Re-scaffold APIs and Controllers + +For each API resource in your original project, re-scaffold them in the new project. + +### 3.1 Identify all your APIs + +Review your backup project (`../migration-backup/`) to identify all APIs. **It's recommended to check the backup directory +regardless of whether you have a `PROJECT` file**, as not all resources may have been created using the CLI. + +**Check the directory structure** in your backup to ensure you don't miss any manually created resources: + +- Look in the `api/` directory for `*_types.go` files: + - Single-group: `api/v1/cronjob_types.go` → extract: version `v1`, kind `CronJob`, group from imports + - Multi-group: `api/batch/v1/cronjob_types.go` → extract: group `batch`, version `v1`, kind `CronJob` + +- Check for controllers. The location depends on the Kubebuilder version: + - **Newer versions (v3+):** `internal/controller/cronjob_controller.go` + - **Older versions:** `controllers/cronjob_controller.go` + - A file like `cronjob_controller.go` indicates a controller exists for that kind + +**If you used the CLI to create all APIs from Kubebuilder `v3.0.0+` you should have then in the `PROJECT` file** under the `resources` section, such as: + +```yaml +resources: + - api: + crdVersion: v1 + namespaced: true + controller: true + group: batch + kind: CronJob + version: v1 +``` + + + +### 3.2 Create each API and Controller + +For each API identified in step 3.1, re-scaffold it: + +```bash +kubebuilder create api --group batch --version v1 --kind CronJob +``` + +When prompted: +- Answer **yes** to "Create Resource [y/n]" to generate the API types +- Answer **yes** to "Create Controller [y/n]" if your original project has a controller for this API + +**After creating each API**, update the generated manifests and code: + +```bash +make manifests # Generate CRD, RBAC, and other config files +make generate # Generate code (e.g., DeepCopy methods) +``` + +Then verify everything compiles: + +```bash +make build +``` + +These steps ensure the newly scaffolded API is properly integrated. See the [Quick Start][quick-start] guide for a detailed walkthrough of the API creation workflow. + +Repeat this process for **ALL** APIs in your project. + + + +After creating all resources, regenerate manifests: + +```bash +make manifests +make generate +``` + +### 3.3 Re-scaffold webhooks (if applicable) + +If your original project has webhooks, you need to re-scaffold them. + +**Identify webhooks in your backup project:** + +1. **From directory structure**, look for webhook files: + - Legacy location: `api/v1/_webhook.go` or `api///_webhook.go` + - Current location: `internal/webhook//_webhook.go` + +2. **From `PROJECT` file** (if available), check each resource's webhooks section: + +```yaml +resources: + - api: + ... + webhooks: + defaulting: true + validation: true + webhookVersion: v1 +``` + +**Re-scaffold webhooks:** + +For each resource with webhooks, run: + +```bash +kubebuilder create webhook --group batch --version v1 --kind CronJob --defaulting --programmatic-validation +``` + +**Webhook options:** +- `--defaulting` - creates a defaulting webhook (sets default values) +- `--programmatic-validation` - creates a validation webhook (validates create/update/delete operations) +- `--conversion` - creates a conversion webhook (for multi-version APIs, see next section) + +### 3.4 Re-scaffold conversion webhooks (if applicable) + +If your project has multi-version APIs with conversion webhooks, you need to set up the hub-spoke conversion pattern. + + + +**Setting up conversion webhooks:** + +The conversion webhook is created for the **hub** version, with spoke versions specified using the `--spoke` flag: + +```bash +kubebuilder create webhook --group batch --version v2 --kind CronJob --conversion --spoke v1 +``` + +This command: +- Creates the conversion webhook infrastructure for version `v2` (the hub) +- Sets up conversion for version `v1` (the spoke) to convert to/from `v2` +- Generates `cronjob_conversion.go` files with conversion method stubs + +**For multiple spokes**, you can specify them as a comma-separated list: + +```bash +kubebuilder create webhook --group batch --version v2 --kind CronJob --conversion --spoke v1,v1alpha1 +``` + +This sets up `v2` as the hub with both `v1` and `v1alpha1` as spokes. + +**What you need to implement:** + +The command generates method stubs that you'll fill in during Step 4: +- **Hub version**: Implement `Hub()` method (usually just a marker) +- **Spoke versions**: Implement `ConvertTo(hub)` and `ConvertFrom(hub)` methods with your conversion logic + +See the [Multi-Version Tutorial][multiversion-tutorial] for comprehensive guidance on implementing the conversion logic. + + + + + +After scaffolding all webhooks, verify everything compiles: + +```bash +make manifests +make generate +make build +``` + +## Step 4: Port Your Custom Code + +Now you need to manually port your custom business logic and configurations from the backup to the new project. + + + +### 4.1 Port API definitions + +Compare and merge your custom API fields and markers from your backup project. + +**Files to compare:** + +- **Single-group:** `api/v1/_types.go` +- **Multi-group:** `api///_types.go` + +**What to port:** + +1. **Custom fields** in Spec and Status structs +2. **Validation markers** - e.g., `+kubebuilder:validation:Minimum=0`, `+kubebuilder:validation:Pattern=...` +3. **CRD generation markers** - e.g., `+kubebuilder:printcolumn`, `+kubebuilder:resource:scope=Cluster` +4. **SubResources** - e.g., `+kubebuilder:subresource:status`, `+kubebuilder:subresource:scale` +5. **Documentation comments** - Used for CRD descriptions + +See [CRD Generation][crd-generation], [CRD Validation][crd-validation], and [Markers][markers] for all available markers. + +After porting API definitions, regenerate and verify: + +```bash +make manifests # Generate CRD manifests from your types +make generate # Generate DeepCopy methods +``` + +This ensures your API types and CRD manifests are properly generated before moving forward. + +### 4.2 Port controller logic + +**Files to compare:** + +- **File location:** `internal/controller/_controller.go` (or `controllers/` in older versions) + +**What to port:** + +1. **Reconcile function implementation** - Your core business logic +2. **Helper functions** - Any additional functions in the controller file +3. **RBAC markers** - `+kubebuilder:rbac:groups=...,resources=...,verbs=...` +4. **Additional watches** - Custom watch configurations in `SetupWithManager` +5. **Imports** - Any additional packages your controller needs +6. **Struct fields** - Custom fields added to the Reconciler struct + +See [RBAC Markers][rbac-markers] for details on permission markers. + +After porting controller logic, regenerate manifests and verify compilation: + +```bash +make generate +make manifests +make build +``` + +### 4.3 Port webhook implementations + +Webhooks have changed location between Kubebuilder versions. Be aware of the path differences: + +**Legacy webhook location** (Kubebuilder v3 and earlier): +- `api/v1/_webhook.go` +- `api///_webhook.go` + +**Current webhook location** (Kubebuilder v4+): +- `internal/webhook/v1/_webhook.go` +- `internal/webhook//_webhook.go` + +**What to port:** + +1. **Defaulting webhook** - `Default()` method implementation +2. **Validation webhook** - `ValidateCreate()`, `ValidateUpdate()`, `ValidateDelete()` methods +3. **Conversion webhook** - `ConvertTo()` and `ConvertFrom()` methods (for multi-version APIs) +4. **Helper functions** - Any validation or defaulting helper functions +5. **Webhook markers** - Usually auto-generated, but verify they match your needs + + + +See [Webhook Overview][webhook-overview], [Admission Webhook][admission-webhook], and the [Multi-Version Tutorial][multiversion-tutorial] for details. + +**For conversion webhooks:** + +If you have conversion webhooks, ensure you used the `create webhook --conversion --spoke ` command in Step 3.4. This sets up the hub-spoke infrastructure automatically. You only need to fill in the conversion logic in the `ConvertTo()` and `ConvertFrom()` methods in your spoke versions, and the `Hub()` method in your hub version. + +The command creates all the necessary boilerplate - you just implement the business logic for converting fields between versions. + +After porting webhooks, regenerate and verify: + +```bash +make generate +make manifests +make build +``` + +### 4.4 Configure Kustomize manifests + +The `config/` directory contains Kustomize manifests for deploying your operator. Compare with your backup to ensure all configurations are properly set up. + +**Review and update these directories:** + +1. **`config/default/kustomization.yaml`** - Main kustomization file + - Ensure that webhook configurations is enabled if you have webhooks (`uncomment webhook-related patches`) + - Ensure that cert-manager is enabled if using webhooks (`uncomment certmanager resources`) + - Enable or disable metrics endpoint based on your original configuration + - Review namespace and name prefix settings + +2. **`config/manager/`** - Controller manager deployment + - Usually no changes needed unless you have customizations, such as: + - If needed: compare resource limits and requests with your backup + - If needed: check environment variables + +3. **`config/rbac/`** - RBAC configurations + - Usually auto-generated from markers - no manual changes needed + - Only check if you have custom role bindings or service account configurations not covered by markers + +4. **`config/webhook/`** - Webhook configurations (if applicable) + - Usually auto-generated - no manual changes needed + - Only check if you have custom webhook service or certificate configurations + +5. **`config/samples/`** - Sample CR manifests + - Copy your sample resources from the backup + +After configuring Kustomize, verify the manifests build correctly: + +```bash +make all +make build-installer +``` + +### 4.5 Port main.go customizations (if any) + +**File:** `cmd/main.go` + +Most projects don't need to customize `main.go` as Kubebuilder handles all the standard setup automatically +(registering APIs, setting up controllers and webhooks, manager initialization, metrics, etc.). + +Only port customizations that are not part of the standard scaffold. Compare your backup `main.go` with the +new scaffolded one to identify any custom logic you added. + +### 4.6 Port additional customizations + +Now try building and testing the project to identify any missing pieces: + +```bash +make all +``` + +If you encounter issues, you may need to port additional customizations from your backup: + +**Dependencies** (`go.mod`): +- Compare your backup `go.mod` with the new one +- Add any additional dependencies not part of the standard scaffold: + ```bash + go get @ + ``` +- Then tidy up: + ```bash + go mod tidy + ``` + +Compare your project structure with your backup to identify any other custom files or directories you may have added, such as: + +- Compare the two **Makefiles** carefully using diff tools you may have custom targets: deployment helpers, code generation scripts, etc. +- Compare the **Dockerfile** you may have some custom build configurations: +- Ensure that you ported any testing-related files and configurations if you have tests in your project. + + + +After porting all customizations, run the full build and test cycle: + +```bash +make all +``` + +## Step 5: Test and Deploy + +Thoroughly test your migrated project to ensure everything works as expected. + +## Additional Resources + +- [Migration Overview](../migrations.md) - Overview of all migration options +- [PROJECT File Reference][project-config] - Understanding the PROJECT file +- [What's in a basic project?][basic-project-doc] - Understanding project structure +- [Alpha Generate Command](../reference/commands/alpha_generate.md) - Automated re-scaffolding +- [Alpha Update Command](../reference/commands/alpha_update.md) - Automated migration +- [Using External Types][external-types] - Controllers for types not defined in your project +- [CRD Generation][crd-generation] - Generating CRDs from Go types +- [CRD Validation][crd-validation] - Adding validation to your APIs +- [Markers][markers] - All available markers for code generation +- [RBAC Markers][rbac-markers] - Generating RBAC manifests +- [Webhook Overview][webhook-overview] - Understanding webhooks +- [Admission Webhook][admission-webhook] - Implementing admission webhooks +- [Multi-Version Tutorial][multiversion-tutorial] - Handling multiple API versions +- [Deploying cert-manager][cert-manager] - Required for webhooks +- [Configuring EnvTest][envtest] - Testing with EnvTest + +[quick-start]: ../quick-start.md +[project-config]: ../reference/project-config.md +[basic-project-doc]: ../cronjob-tutorial/basic-project.md +[external-types]: ../reference/using_an_external_resource.md +[external-types-webhooks]: ../reference/using_an_external_resource.md#creating-a-webhook-to-manage-an-external-type +[crd-generation]: ../reference/generating-crd.md +[crd-validation]: ../reference/markers/crd-validation.md +[markers]: ../reference/markers.md +[rbac-markers]: ../reference/markers/rbac.md +[webhook-overview]: ../reference/webhook-overview.md +[admission-webhook]: ../reference/admission-webhook.md +[multiversion-tutorial]: ../multiversion-tutorial/tutorial.md +[cert-manager]: ../cronjob-tutorial/cert-manager.md +[envtest]: ../reference/envtest.md +[standard-go-project]: https://github.com/golang-standards/project-layout diff --git a/docs/book/src/migration/manually_migration_guide_gov3_to_gov4.md b/docs/book/src/migration/manually_migration_guide_gov3_to_gov4.md deleted file mode 100644 index d4cac5a0b4b..00000000000 --- a/docs/book/src/migration/manually_migration_guide_gov3_to_gov4.md +++ /dev/null @@ -1,210 +0,0 @@ -# Migration from go/v3 to go/v4 by updating the files manually - -Make sure you understand the [differences between Kubebuilder go/v3 and go/v4][v3vsv4] -before continuing. - -Please ensure you have followed the [installation guide][quick-start] -to install the required components. - -The following guide describes the manual steps required to upgrade your PROJECT config file to begin using `go/v4`. - -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][migration-guide-gov3-to-gov4] instead. - -## Migration from project config version "go/v3" to "go/v4" - -Update the `PROJECT` file layout which stores information about the resources that are used to enable plugins make -useful decisions while scaffolding. The `layout` field indicates the scaffolding and the primary plugin version in use. - -### Steps to migrate - -#### Migrate the layout version into the PROJECT file - -The following steps describe the manual changes required to bring the project configuration file (`PROJECT`). -These change will add the information that Kubebuilder would add when generating the file. This file can be found in the root directory. - -Update the PROJECT file by replacing: - -```yaml -layout: -- go.kubebuilder.io/v3 -``` - -With: - -```yaml -layout: -- go.kubebuilder.io/v4 - -``` - -#### Changes to the layout - -##### New layout: - -- The directory `apis` was renamed to `api` to follow the standard -- The `controller(s)` directory has been moved under a new directory called `internal` and renamed to singular as well `controller` -- The `main.go` previously scaffolded in the root directory has been moved under a new directory called `cmd` - -Therefore, you can check the changes in the layout results into: - -```sh -... -├── cmd -│ └── main.go -├── internal -│ └── controller -└── api -``` - -##### Migrating to the new layout: - -- Create a new directory `cmd` and move the `main.go` under it. -- If your project support multi-group the APIs are scaffold under a directory called `apis`. Rename this directory to `api` -- Move the `controllers` directory under the `internal` and rename it for `controller` -- Now ensure that the imports will be updated accordingly by: - - Update the `main.go` imports to look for the new path of your controllers under the `internal/controller` directory - -**Then, let's update the scaffolds paths** - -- Update the Dockerfile to ensure that you will have: - -``` -COPY cmd/main.go cmd/main.go -COPY api/ api/ -COPY internal/controller/ internal/controller/ -``` - -Then, replace: - -``` -RUN CGO_ENABLED=0 GOOS=${TARGETOS:-linux} GOARCH=${TARGETARCH} go build -a -o manager main.go - -``` - -With: - -``` -RUN CGO_ENABLED=0 GOOS=${TARGETOS:-linux} GOARCH=${TARGETARCH} go build -a -o manager cmd/main.go -``` - -- Update the Makefile targets to build and run the manager by replacing: - -``` -.PHONY: build -build: manifests generate fmt vet ## Build manager binary. - go build -o bin/manager main.go - -.PHONY: run -run: manifests generate fmt vet ## Run a controller from your host. - go run ./main.go -``` - -With: - -``` -.PHONY: build -build: manifests generate fmt vet ## Build manager binary. - go build -o bin/manager cmd/main.go - -.PHONY: run -run: manifests generate fmt vet ## Run a controller from your host. - go run ./cmd/main.go -``` - -- Update the `internal/controller/suite_test.go` to set the path for the `CRDDirectoryPaths`: - -Replace: - -``` -CRDDirectoryPaths: []string{filepath.Join("..", "config", "crd", "bases")}, -``` - -With: - -``` -CRDDirectoryPaths: []string{filepath.Join("..", "..", "config", "crd", "bases")}, -``` - -Note that if your project has multiple groups (`multigroup:true`) then the above update should result into `"..", "..", "..",` instead of `"..",".."` - -#### Now, let's update the PATHs in the PROJECT file accordingly - -The PROJECT tracks the paths of all APIs used in your project. Ensure that they now point to `api/...` as the following example: - -**Before update:** -``` - group: crew - kind: Captain - path: sigs.k8s.io/kubebuilder/testdata/project-v4/apis/crew/v1 -``` - -**After Update:** -``` - - group: crew - kind: Captain - path: sigs.k8s.io/kubebuilder/testdata/project-v4/api/crew/v1 -``` - -### Update kustomize manifests with the changes made so far - -- Update the manifest under `config/` directory with all changes performed in the default scaffold done with `go/v4` 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 Custom Resources samples specified into `config/samples`. _(see for example `testdata/project-v4/config/samples/kustomization.yaml`)_ - - - -### If you have webhooks: - -Replace the import `admissionv1beta1 "k8s.io/api/admission/v1beta1"` with `admissionv1 "k8s.io/api/admission/v1"` in the webhook test files - -### Makefile updates - -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 dependencies - -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. - -### Verification - -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` 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` plugin, -(ie) using `kubebuilder init --domain tutorial.kubebuilder.io plugins=go/v4` 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 controller-gen after you update the Makefile) -- `make all` (to ensure that you are able to build and perform all operations) - -[v3vsv4]: v3vsv4.md -[quick-start]: ./../quick-start.md#installation -[migration-guide-gov3-to-gov4]: migration_guide_gov3_to_gov4.md -[controller-tools]: https://github.com/kubernetes-sigs/controller-tools/releases -[controller-runtime]: https://github.com/kubernetes-sigs/controller-runtime/releases -[multi-group]: multi-group.md - diff --git a/docs/book/src/migration/migration_guide_gov3_to_gov4.md b/docs/book/src/migration/migration_guide_gov3_to_gov4.md deleted file mode 100644 index 8ccd94de4f9..00000000000 --- a/docs/book/src/migration/migration_guide_gov3_to_gov4.md +++ /dev/null @@ -1,161 +0,0 @@ -# Migration from go/v3 to go/v4 - -Make sure you understand the [differences between Kubebuilder go/v3 and go/v4][v3vsv4] -before continuing. - -Please ensure you have followed the [installation guide][quick-start] -to install the required components. - -The recommended way to migrate a `go/v3` project is to create a new `go/v4` project and -copy over the API and the reconciliation code. The conversion will end up with a -project that looks like a native go/v4 project layout (latest version). - - - -However, in some cases, it's possible to do an in-place upgrade (i.e. reuse the go/v3 project layout, upgrading -the PROJECT file, and scaffolds manually). For further information see [Migration from go/v3 to go/v4 by updating the files manually][manually-upgrade] - -## Initialize a go/v4 Project - - - -Create a new directory with the name of your project. Note that -this name is used in the scaffolds to create the name of your manager Pod and of the Namespace where the Manager is deployed by default. - -```bash -$ mkdir migration-project-name -$ cd migration-project-name -``` - -Now, we need to initialize a go/v4 project. Before we do that, we'll need -to initialize a new go module if we're not on the `GOPATH`. While technically this is -not needed inside `GOPATH`, it is still recommended. - -```bash -go mod init tutorial.kubebuilder.io/migration-project -``` - - - -Now, we can finish initializing the project with kubebuilder. - -```bash -kubebuilder init --domain tutorial.kubebuilder.io --plugins=go/v4 -``` - - - -## Migrate APIs and Controllers - -Next, we'll re-scaffold out the API types and controllers. - - - -```bash -kubebuilder create api --group batch --version v1 --kind CronJob -``` - -### Migrate the APIs - - - -Now, let's copy the API definition from `api/v1/_types.go` in our old project to the new one. - -These files have not been modified by the new plugin, so you should be able to replace your freshly scaffolded files by your old one. There may be some cosmetic changes. So you can choose to only copy the types themselves. - -### Migrate the Controllers - -Now, let's migrate the controller code from `controllers/cronjob_controller.go` in our old project to `internal/controller/cronjob_controller.go` in the new one. - -## Migrate the Webhooks - - - -Now let's scaffold the webhooks for our CRD (CronJob). We'll need to run the -following command with the `--defaulting` and `--programmatic-validation` flags -(since our test project uses defaulting and validating webhooks): - -```bash -kubebuilder create webhook --group batch --version v1 --kind CronJob --defaulting --programmatic-validation -``` - -Now, let's copy the webhook definition from `api/v1/_webhook.go` from our old project to the new one. - -## Others - -If there are any manual updates in `main.go` in v3, we need to port the changes to the new `main.go`. We'll also need to ensure all of needed controller-runtime `schemes` have been registered. - -If there are additional manifests added under config directory, port them as well. Please, be aware that -the new version go/v4 uses Kustomize v5x and no longer Kustomize v4. Therefore, if added customized -implementations in the config you need to ensure that they can work with Kustomize v5 and if not -update/upgrade any breaking change that you might face. - -In v4, installation of Kustomize has been changed from bash script to `go get`. Change the `kustomize` dependency in Makefile to -``` -.PHONY: kustomize -kustomize: $(KUSTOMIZE) ## Download kustomize locally if necessary. If wrong version is installed, it will be removed before downloading. -$(KUSTOMIZE): $(LOCALBIN) - @if test -x $(LOCALBIN)/kustomize && ! $(LOCALBIN)/kustomize version | grep -q $(KUSTOMIZE_VERSION); then \ - echo "$(LOCALBIN)/kustomize version is not expected $(KUSTOMIZE_VERSION). Removing it before installing."; \ - rm -rf $(LOCALBIN)/kustomize; \ - fi - test -s $(LOCALBIN)/kustomize || GOBIN=$(LOCALBIN) GO111MODULE=on go install sigs.k8s.io/kustomize/kustomize/v5@$(KUSTOMIZE_VERSION) -``` - -Change the image name in the Makefile if needed. - -## Verification - -Finally, we can run `make` and `make docker-build` to ensure things are working -fine. - -[v3vsv4]: v3vsv4.md -[quick-start]: ./../quick-start.md#installation -[controller-tools]: https://github.com/kubernetes-sigs/controller-tools/releases -[controller-runtime]: https://github.com/kubernetes-sigs/controller-runtime/releases -[multi-group]: multi-group.md -[manually-upgrade]: manually_migration_guide_gov3_to_gov4.md -[project-file]: ../reference/project-config.md diff --git a/docs/book/src/migration/v3-plugins.md b/docs/book/src/migration/v3-plugins.md deleted file mode 100644 index c04e9d77c8b..00000000000 --- a/docs/book/src/migration/v3-plugins.md +++ /dev/null @@ -1,8 +0,0 @@ -# V3 - Plugins Layout Migration Guides - -Following the migration guides from the plugins versions. Note that the plugins ecosystem -was introduced with Kubebuilder v3.0.0 release where the go/v3 version is the default layout -since `28 Apr 2021`. - -Therefore, you can check here how to migrate the projects built from Kubebuilder 3.x with -the plugin go/v3 to the latest. diff --git a/docs/book/src/migration/v3vsv4.md b/docs/book/src/migration/v3vsv4.md deleted file mode 100644 index 4e32da8b903..00000000000 --- a/docs/book/src/migration/v3vsv4.md +++ /dev/null @@ -1,75 +0,0 @@ -# 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 version of the Golang plugin `go/v4`. - -The details of all changes (breaking or otherwise) can be found in: - -- [controller-runtime][controller-runtime] -- [controller-tools][controller-tools] -- [kustomize][kustomize-release] -- [kb-releases][kb-releases] release notes. - -## 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][standard-go-project] -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][kb-releases], 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. - -- [Migration Guide go/v3 to go/v4][migration-guide-gov3-to-gov4] **(Recommended)** - -### 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. - -- [Migrating to go/v4 by updating the files manually][manually-upgrade] - -[plugins-phase1-design-doc]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/designs/extensible-cli-and-scaffolding-plugins-phase-1.md -[plugins-phase1-design-doc-1.5]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/designs/extensible-cli-and-scaffolding-plugins-phase-1-5.md -[plugins-phase2-design-doc]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/designs/extensible-cli-and-scaffolding-plugins-phase-2.md -[plugins-section]: ./../plugins/plugins.md -[kustomize]: https://github.com/kubernetes-sigs/kustomize/releases/tag/kustomize%2Fv4.0.0 -[go/v4-doc]: ./../plugins/go-v4-plugin.md -[migration-guide-gov3-to-gov4]: migration_guide_gov3_to_gov4.md -[manually-upgrade]: manually_migration_guide_gov3_to_gov4.md -[basic-project-doc]: ./../cronjob-tutorial/basic-project.md -[standard-go-project]: https://github.com/golang-standards/project-layout -[controller-runtime]: https://github.com/kubernetes-sigs/controller-runtime -[controller-tools]: https://github.com/kubernetes-sigs/controller-tools -[kustomize-release]: https://github.com/kubernetes-sigs/kustomize/releases/tag/kustomize%2Fv5.0.0 -[kb-releases]: https://github.com/kubernetes-sigs/kubebuilder/releases diff --git a/docs/book/src/migrations.md b/docs/book/src/migrations.md index cc1fe70b4a8..1280035159b 100644 --- a/docs/book/src/migrations.md +++ b/docs/book/src/migrations.md @@ -1,78 +1,138 @@ # 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. +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. -This section details what’s required to migrate, between different versions of Kubebuilder scaffolding, -as well as to more complex project layout structures. +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`). -The manual approach can be error-prone. That is why Kubebuilder introduces new alpha commands -that help streamline the migration process. +Kubebuilder provides multiple migration paths to suit your workflow. Choose the approach that best fits your needs. -## Manual Migration + -## Understanding the PROJECT File (Introduced in `v3.0.0`) +