From 91c15361505d9971957c4f0027ab41fddee5d5bf 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 Co-authored-by: Camila Macedo <7708031+camilamacedo86@users.noreply.github.com> Signed-off-by: Juan-Luis de Sousa-Valadas Castaño --- docs/book/src/migration/multi-group.md | 110 ++++++++++++++----------- 1 file changed, 64 insertions(+), 46 deletions(-) diff --git a/docs/book/src/migration/multi-group.md b/docs/book/src/migration/multi-group.md index fd6a15266c6..f3e318b19cc 100644 --- a/docs/book/src/migration/multi-group.md +++ b/docs/book/src/migration/multi-group.md @@ -4,32 +4,35 @@

Note

-Multi-group scaffolding support was not present in the initial version of -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 -to move the old API groups to the new layout. - - - -While Kubebuilder v2 will not scaffold out a project structure compatible +While Kubebuilder will not scaffold out a project structure compatible with multiple API groups in the same repository by default, it's possible to modify the default project structure to support it. + + Let's migrate the [CronJob example][cronjob-tutorial]. +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 +to move the old API groups to the new layout. + 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: @@ -38,58 +41,72 @@ can check `api/v1/groupversion_info.go` to find that out: package v1 ``` -Then, we'll rename `api` to `apis` to be more clear, and we'll move our -existing APIs into a new subdirectory, "batch": +Then, we'll rename move our existing APIs into a new subdirectory, "batch": ```bash -mkdir apis/batch -mv api/* apis/batch -# After ensuring that all was moved successfully remove the old directory `api/` -rm -rf api/ +mv api/* api/batch ``` - -After moving the APIs to a new directory, the same needs to be applied to the controllers: +After moving the APIs to a new directory, the same needs to be applied to the controllers. For go/v4: ```bash -mkdir controllers/batch -mv controllers/* controllers/batch/ +mkdir internal/controller/batch +mv internal/controller/* internal/controller/batch/ ``` +For go/v3: +```bash +mkdir controller/batch +mv controller/* controller/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, 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, we'll run the command which enable the multi-group layout in the project: +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. -``` -kubebuilder edit --multigroup=true -``` +For instance, for a file: -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" +# 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 -repo: tutorial.kubebuilder.io/project +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" ``` -Note that this option indicates to Kubebuilder that this is a multi-group project. +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`. -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. -Remember to update the references afterwards. +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 `controllers//suite_test.go` file. We need to add additional `".."` to our CRD directory relative path as shown below. +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") @@ -104,3 +121,4 @@ 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" +[migration-guide]: /migration/migration_guide_gov3_to_gov4.md "Migration from go/v3 to go/v4"