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 index cae361c45ca..7ce8757ae47 100644 --- a/docs/book/src/migration/manually_migration_guide_gov3_to_gov4.md +++ b/docs/book/src/migration/manually_migration_guide_gov3_to_gov4.md @@ -16,11 +16,17 @@ The recommended upgrade approach is to follow the [Migration Guide go/v3 to go/v ## 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. +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. -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 + +#### 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: +Update the PROJECT file by replacing: ```yaml layout: @@ -35,16 +41,120 @@ layout: ``` -### Steps to migrate +#### Changes the layout -- 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 "k8s.io/api/admission/v1beta1"` with `admissionv1 "k8s.io/api/admission/v1"` in the webhook test files +##### Now, let's perform the layout changes to comply within: + +- 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 +``` + +##### In this way, you will need to: + +- 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 `pkg` directory + - Update all controllers imports to look for the new path of your apis under the `pkg` 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 `pkg/api/...` as the following example: + +Before update: + group: crew + kind: Captain + path: sigs.k8s.io/kubebuilder/testdata/project-v4/api/crew/v1 +``` + +After Update: + +``` + group: crew + kind: Captain + path: sigs.k8s.io/kubebuilder/testdata/project-v4/apis/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-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 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 diff --git a/docs/book/src/migration/v3vsv4.md b/docs/book/src/migration/v3vsv4.md index 1cd0e39031f..b579ed191b3 100644 --- a/docs/book/src/migration/v3vsv4.md +++ b/docs/book/src/migration/v3vsv4.md @@ -20,6 +20,8 @@ The details of all changes (breaking or otherwise) can be found in: - 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 `pkg`, controller(s) under a new directory called `internal` and the `main.go` under a new directory named `cmd`