Skip to content

Latest commit

 

History

History
124 lines (94 loc) · 4.67 KB

multi-group.md

File metadata and controls

124 lines (94 loc) · 4.67 KB
Raw

Single Group to Multi-Group

Note

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.

Note that the process mainly is to ensure that your API(s) and controller(s) will be moved under new directories with their respective group name.

Let's migrate the CronJob example.

Instructions vary per project layout

You can verify the version by looking at the PROJECT file. The currently default and recommended version is go/v4.

The layout go/v3 is deprecated, if you are using go/v3 it is recommended that you migrate to go/v4, however this documentation is still valid. Migration from go/v3 to go/v4.

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 rename move our existing APIs into a new subdirectory, "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/

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).