项目配置（Project Config）

概览（Overview）

Project Config 描述了一个 Kubebuilder 项目的配置信息。使用 CLI（KB 3.0+）脚手架生成的项目，都会在项目根目录生成 PROJECT 文件。该文件会记录用于生成项目与 API 的插件及输入数据，便于后续插件在脚手架过程中基于这些上下文做出正确决策。

示例（Example）

下面是一个使用 Deploy Image 插件生成、且包含两个 API 的项目所对应的 PROJECT 示例：

# 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: testproject.org
cliVersion: v4.6.0
layout:
  - go.kubebuilder.io/v4
plugins:
  deploy-image.go.kubebuilder.io/v1-alpha:
    resources:
      - domain: testproject.org
        group: example.com
        kind: Memcached
        options:
          containerCommand: memcached,--memory-limit=64,-o,modern,-v
          containerPort: "11211"
          image: memcached:1.4.36-alpine
          runAsUser: "1001"
        version: v1alpha1
      - domain: testproject.org
        group: example.com
        kind: Busybox
        options:
          image: busybox:1.28
        version: v1alpha1
projectName: project-v4-with-deploy-image
repo: sigs.k8s.io/kubebuilder/testdata/project-v4-with-deploy-image
resources:
  - api:
      crdVersion: v1
      namespaced: true
    controller: true
    domain: testproject.org
    group: example.com
    kind: Memcached
    path: sigs.k8s.io/kubebuilder/testdata/project-v4-with-deploy-image/api/v1alpha1
    version: v1alpha1
    webhooks:
      validation: true
      webhookVersion: v1
  - api:
      crdVersion: v1
      namespaced: true
    controller: true
    domain: testproject.org
    group: example.com
    kind: Busybox
    path: sigs.k8s.io/kubebuilder/testdata/project-v4-with-deploy-image/api/v1alpha1
    version: v1alpha1
version: "3"

为什么要存储所用插件与输入数据？

主要动机包括但不限于：

检查在现有插件之上能否继续脚手架另一个插件，即在串联多个插件时的兼容性判断。
约束允许/不允许的操作。例如：当前布局是否允许按组拆分、继续为不同 Group 的 API 进行脚手架生成。
校验 CLI 操作所需的数据是否可用，例如确保仅能为已存在的 API 创建 Webhook。

请注意，Kubebuilder 不仅是一个 CLI 工具，也可以作为库被复用，用于创建自定义插件/工具、在既有项目之上提供辅助与定制（例如 Operator-SDK 就是这样做的）。SDK 基于 Kubebuilder 构建插件，使其支持其他语言或为用户提供集成其项目的各种辅助能力，例如整合 Operator Framework/OLM。关于如何创建自定义插件，可查看插件文档。

另外，PROJECT 文件还能帮助我们实现“自动再脚手架（re-scaffold）”以便简化项目升级：把 API 及其配置与版本等必要元数据集中保存在 PROJECT 中，就能在插件版本迁移时自动化地再脚手架项目。更多设计说明。

版本（Versioning）

Project Config 会随布局（layout）产生版本。详见 Versioning。

布局定义（Layout Definition）

PROJECT 版本 3 的布局示例：

domain: testproject.org
cliVersion: v4.6.0
layout:
  - go.kubebuilder.io/v4
plugins:
  deploy-image.go.kubebuilder.io/v1-alpha:
    resources:
      - domain: testproject.org
        group: example.com
        kind: Memcached
        options:
          containerCommand: memcached,--memory-limit=64,-o,modern,-v
          containerPort: "11211"
          image: memcached:memcached:1.6.26-alpine3.19
          runAsUser: "1001"
        version: v1alpha1
      - domain: testproject.org
        group: example.com
        kind: Busybox
        options:
          image: busybox:1.36.1
        version: v1alpha1
projectName: project-v4-with-deploy-image
repo: sigs.k8s.io/kubebuilder/testdata/project-v4-with-deploy-image
resources:
  - api:
      crdVersion: v1
      namespaced: true
    controller: true
    domain: testproject.org
    group: example.com
    kind: Memcached
    path: sigs.k8s.io/kubebuilder/testdata/project-v4-with-deploy-image/api/v1alpha1
    version: v1alpha1
    webhooks:
      validation: true
      webhookVersion: v1
  - api:
      crdVersion: v1
      namespaced: true
    controller: true
    domain: testproject.org
    group: example.com
    kind: Busybox
    path: sigs.k8s.io/kubebuilder/testdata/project-v4-with-deploy-image/api/v1alpha1
    version: v1alpha1
version: "3"

下面是各字段含义说明：

Field	Description
`cliVersion`	记录通过 `init` 脚手架生成项目时所使用的 CLI 版本，用于定位所用工具版本，便于排错并确保与后续更新兼容。
`layout`	定义全局插件。例如 `init --plugins="go/v4,deploy-image/v1-alpha"` 表示后续执行的任意子命令都会串联调用这两个插件的实现。
`domain`	项目的域名。可在执行 `init` 子命令时通过 `--domain` 指定。
`plugins`	定义用于自定义脚手架的插件。例如仅为某个特定 API 使用可选插件 `deploy-image/v1-alpha`：`kubebuilder create api [options] --plugins=deploy-image/v1-alpha`。
`projectName`	项目名称。用于生成 manager 相关数据。默认取项目目录名，也可在 `init` 时通过 `--project-name` 指定。
`repo`	项目仓库（Go 模块名），例如 `github.com/example/myproject-operator`。
`resources`	项目中已脚手架生成的所有资源（数组）。
`resources.api`	通过 `create api` 子命令生成的 API 信息。
`resources.api.crdVersion`	生成 CRD 资源所使用的 Kubernetes API 版本（`apiVersion`）。
`resources.api.namespaced`	API 的 RBAC 作用域，是 Namespaced 还是 Cluster 级别。
`resources.controller`	指示该 API 是否已生成对应的 Controller。
`resources.domain`	资源的域名。来自项目初始化时的 `--domain`，或在为外部类型脚手架 Controller 时通过 `--external-api-domain` 指定。
`resources.group`	资源的 GVK 中的 Group，来自执行 `create api` 时的 `--group`。
`resources.version`	资源的 GVK 中的 Version，来自执行 `create api` 时的 `--version`。
`resources.kind`	资源的 GVK 中的 Kind，来自执行 `create api` 时的 `--kind`。
`resources.path`	API 资源的 import 路径。默认是 `<repo>/api/<kind>`；若添加的是外部类型或核心类型，路径会不同。核心类型的路径映射见此处；外部类型也可以通过 `--external-api-path` 显式指定。
`resources.core`	当使用的 Group 来自 Kubernetes 核心 API，且该 API 资源未在本项目中定义时为 `true`。
`resources.external`	当使用 `--external-api-path` 为外部类型生成脚手架时为 `true`。
`resources.webhooks`	当执行 `create webhook` 时记录 webhook 相关数据。
`resources.webhooks.spoke`	转换（conversion）webhook 中，作为 Spoke 的 API 版本；对应的 Hub 版本在另外指定。
`resources.webhooks.webhookVersion`	生成 webhook 资源所使用的 Kubernetes API 版本（`apiVersion`）。
`resources.webhooks.conversion`	使用 `--conversion` 生成转换型 webhook 时为 `true`。
`resources.webhooks.defaulting`	使用 `--defaulting` 生成默认化（Mutating）webhook 时为 `true`。
`resources.webhooks.validation`	使用 `--programmatic-validation` 生成校验型（Validating）webhook 时为 `true`。