From e812a438db7fe7173011a40b27382d2e8df94d1d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan-Luis=20de=20Sousa-Valadas=20Casta=C3=B1o?= Date: Wed, 10 May 2023 16:01:48 +0200 Subject: [PATCH] doc: Fix multigroup migration guide for v4 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Varsha Signed-off-by: Juan-Luis de Sousa-Valadas Castaño --- docs/book/src/migration/multi-group.md | 124 +++++++++++++++++++++---- 1 file changed, 106 insertions(+), 18 deletions(-) diff --git a/docs/book/src/migration/multi-group.md b/docs/book/src/migration/multi-group.md index fd6a15266c6..a88b2adfa5c 100644 --- a/docs/book/src/migration/multi-group.md +++ b/docs/book/src/migration/multi-group.md @@ -9,7 +9,7 @@ the Kubebuilder v2 scaffolding (as of Kubebuilder v2.0.0). To change the layout of your project to support Multi-Group run the command `kubebuilder edit --multigroup=true`. Once you switch to a multi-group layout, the new Kinds -will be generated in the new layout but additional manual work is needed +will be generated in the new layout but additional manual work is needed to move the old API groups to the new layout. @@ -21,15 +21,14 @@ to modify the default project structure to support it. Let's migrate the [CronJob example][cronjob-tutorial]. +

Using Go/v3

+ Generally, we use the prefix for the API group as the directory name. We can check `api/v1/groupversion_info.go` to find that out: @@ -42,10 +41,10 @@ Then, we'll rename `api` to `apis` to be more clear, and we'll move our existing APIs into a new subdirectory, "batch": ```bash -mkdir apis/batch +mkdir -p apis/batch mv api/* apis/batch # After ensuring that all was moved successfully remove the old directory `api/` -rm -rf api/ +rm -rf api/ ``` @@ -58,8 +57,8 @@ mv controllers/* controllers/batch/ -Next, we'll need to update all the references to the old package name. -For CronJob, that'll be `main.go` and `controllers/batch/cronjob_controller.go`. +Next, we'll need to update all the references to the old package name. +For CronJob, that'll be `main.go` and `controllers/batch/cronjob_controller.go`. If you've added additional files to your project, you'll need to track down imports there as well. @@ -70,9 +69,9 @@ Finally, we'll run the command which enable the multi-group layout in the projec kubebuilder edit --multigroup=true ``` -When the command `kubebuilder edit --multigroup=true` is executed it will add a new line +When the command `kubebuilder edit --multigroup=true` is executed it will add a new line to `PROJECT` that marks this a multi-group project: - + ```yaml version: "2" domain: tutorial.kubebuilder.io @@ -80,13 +79,13 @@ repo: tutorial.kubebuilder.io/project multigroup: true ``` -Note that this option indicates to Kubebuilder that this is a multi-group project. +Note that this option indicates to Kubebuilder that this is a multi-group project. -In this way, if the project is not new and has previous APIs already implemented will be in the previous structure. +In this way, if the project is not new and has previous APIs already implemented will be in the previous structure. Notice that with the `multi-group` project the Kind API's files are -created under `apis//` instead of `api/`. -Also, note that the controllers will be created under `controllers/` instead of `controllers`. -That is the reason why we moved the previously generated APIs with the provided scripts in the previous steps. +created under `apis//` instead of `api/`. +Also, note that the controllers will be created under `controllers/` instead of `controllers`. +That is the reason why we moved the previously generated APIs with the provided scripts in the previous steps. Remember to update the references afterwards. For envtest to install CRDs correctly into the test environment, the relative path to the CRD directory needs to be updated accordingly in each `controllers//suite_test.go` file. We need to add additional `".."` to our CRD directory relative path as shown below. @@ -104,3 +103,92 @@ single-group projects). [multi-group-issue]: https://github.com/kubernetes-sigs/kubebuilder/issues/923 "Kubebuilder Issue #923" [cronjob-tutorial]: /cronjob-tutorial/cronjob-tutorial.md "Tutorial: Building CronJob" + +

Using Go/v4

+ +Generally, we use the prefix for the API group as the directory name. We +can check `api/v1/groupversion_info.go` to find that out: + +```go +// +groupName=batch.tutorial.kubebuilder.io +package v1 +``` + +Then, we'll rename move our existing APIs into a new subdirectory, "batch": + +```bash +mv api/* api/batch +``` + + +After moving the APIs to a new directory, the same needs to be applied to the controllers: + +```bash +mkdir internal/controller/batch +mv internal/controller/* internal/controller/batch/ +``` + + + +Next, we'll need to update all the references to the old package name. +For CronJob, the paths to be replaced would be `main.go` and `controllers/batch/cronjob_controller.go` to their respective locations in the new project structure. + +If you've added additional files to your project, you'll need to track down +imports there as well. + +Finally, fix the PROJECT file manually, the command `kubebuilder edit --multigroup=true` +sets our project to multigroup, but it doesn't fix the path of the existing APIs. +For each resource we need to modify the path. + +For instance, for a file: + +```yaml +# Code generated by tool. DO NOT EDIT. +# This file is used to track the info used to scaffold your project +# and allow the plugins properly work. +# More info: https://book.kubebuilder.io/reference/project-config.html +domain: tutorial.kubebuilder.io +layout: +- go.kubebuilder.io/v4 +multigroup: true +projectName: test +repo: tutorial.kubebuilder.io/project +resources: +- api: + crdVersion: v1 + namespaced: true + controller: true + domain: tutorial.kubebuilder.io + group: batch + kind: CronJob + path: tutorial.kubebuilder.io/project/api/v1beta1 + version: v1beta1 +version: "3" +``` + +Replace `path: tutorial.kubebuilder.io/project/api/v1beta1` for +`path: tutorial.kubebuilder.io/project/api/batch/v1beta1` + + +In this process, if the project is not new and has previous implemented APIs they would still need to be modified as needed. +Notice that with the `multi-group` project the Kind API's files are created under `api//` instead of `api/`. +Also, note that the controllers will be created under `internal/controller/` instead of `internal/controller`. + +That is the reason why we moved the previously generated APIs to their respective locations in the new structure. +Remember to update the references in imports accordingly. + +For envtest to install CRDs correctly into the test environment, the relative path to the CRD directory needs to be updated accordingly in each `internal/controller//suite_test.go` file. We need to add additional `".."` to our CRD directory relative path as shown below. + +```go + By("bootstrapping test environment") + testEnv = &envtest.Environment{ + CRDDirectoryPaths: []string{filepath.Join("..", "..", "config", "crd", "bases")}, + } +``` + +The [CronJob tutorial][cronjob-tutorial] explains each of these changes in +more detail (in the context of how they're generated by Kubebuilder for +single-group projects). + +[multi-group-issue]: https://github.com/kubernetes-sigs/kubebuilder/issues/923 "Kubebuilder Issue #923" +[cronjob-tutorial]: /cronjob-tutorial/cronjob-tutorial.md "Tutorial: Building CronJob" \ No newline at end of file