Single Group to Multi-Group

Let’s migrate the CronJob example.

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:

// +groupName=batch.tutorial.kubebuilder.io
package v1

Then, we’ll move our existing APIs into a new subdirectory named after the group. Considering the CronJob example, subdirectory name is “batch”:

mkdir api/batch
mv api/* api/batch

After moving the APIs to a new directory, the same needs to be applied to the controllers. For go/v4:

mkdir internal/controller/batch
mv internal/controller/* internal/controller/batch/

The same needs to be applied for any pre-existing webhooks:

mkdir internal/webhook/batch
mv internal/webhook/* internal/webhook/batch/

For any new webhook created for a new group, the respective functions will be created under subdirectory internal/webhook/<group>/.

If you are using the deprecated layout go/v3

Then, your layout has not the internal directory. So, you will move the controller(s) under a directory with the name of the API group which it is responsible for manage. ```bash mkdir controller/batch mv controller/* 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:

# 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/<group>/<version> instead of api/<version>. Also, note that the controllers will be created under internal/controller/<group> 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/<group>/suite_test.go file. We need to add additional ".." to our CRD directory relative path as shown below.

    By("bootstrapping test environment")
    testEnv = &envtest.Environment{
        CRDDirectoryPaths: []string{filepath.Join("..", "..", "config", "crd", "bases")},
    }

The CronJob tutorial explains each of these changes in more detail (in the context of how they’re generated by Kubebuilder for single-group projects).