从单 Group 迁移到多 Group（Multi-Group）

下面以 CronJob 示例 进行迁移演示。

将项目切换为多 Group 布局： 运行 kubebuilder edit --multigroup=true。切换后，新建的 Kind 会按多 Group 布局生成；但已有的 API 组需手动迁移到新布局。

通常我们以 API 组前缀作为目录名。可查看 api/v1/groupversion_info.go 获取组名：

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

然后，将现有 API 移动到以组名命名的子目录下。以 CronJob 示例 为例，子目录为 “batch”：

mkdir api/batch
mv api/* api/batch

API 移动后，Controller 也需按相同规则迁移（以 go/v4 为例）：

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

已有的 Webhook 亦需同样处理：

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

后续为新组创建的 Webhook，会生成在 internal/webhook/<group>/ 下。

接着，更新对旧包路径的所有引用。以 CronJob 为例，需调整 main.go 与 controllers/batch/cronjob_controller.go 中的导入路径，指向新结构下的位置。

如果项目中还有其它自定义文件，也需要同步修正导入路径。

最后手动修正 PROJECT 文件。kubebuilder edit --multigroup=true 仅开启多 Group，不会修复已存在 API 的 path。需要为每个资源更新其路径。

例如，原文件：

# 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"

需将 path: tutorial.kubebuilder.io/project/api/v1beta1 替换为 path: tutorial.kubebuilder.io/project/api/batch/v1beta1。

对于非新建项目，已实现的旧 API 也需按需调整。 注意在多 Group 布局下，Kind 的 API 文件位置为 api/<group>/<version>（而非 api/<version>）；控制器位置为 internal/controller/<group>（而非 internal/controller）。

这就是我们需要把既有 API/Controller 移动到新结构对应位置的原因。别忘了同步更新导入路径。

为使 envtest 能正确安装 CRD 到测试环境，需要在每个 internal/controller/<group>/suite_test.go 中更新 CRD 目录的相对路径，多加一层 ".."，例如：

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

CronJob 教程对上述变更有更详细的说明（针对单 Group 项目的自动生成情况）。