📚 课程目录第2章 Operator SDK与项目脚手架

2. Operator SDK与项目脚手架

Operator SDK 是 Red Hat 主导的 Operator 开发框架，它把 Kubebuilder 的控制器运行时能力与 Operator 生命周期管理工具（OLM）打包在一起，为 Go 语言 Operator 提供了一套标准化的项目脚手架。所谓“脚手架”，本质上是 SDK 根据你声明的 API 组、版本、Kind 和领域（domain）自动生成的一整套目录、代码骨架和构建脚本。理解这套脚手架，是后续编写 Reconcile 逻辑、打包镜像、生成 Bundle 的前提。

一、初始化一个 Go Operator 项目

Operator SDK 提供三种初始化模式：operator-sdk init 用于创建项目骨架，operator-sdk create api 用于生成 API 类型和控制器，operator-sdk create webhook 用于生成准入 Webhook。以本课程贯穿的示例为例，我们构建一个管理自定义资源 AppService 的 Operator，API 组为 apps.example.com，版本 v1alpha1，Kind 为 AppService。

# 1. 创建项目骨架，指定模块路径与仓库地址
operator-sdk init \
  --domain example.com \
  --repo github.com/example/app-operator \
  --project-name app-operator

# 2. 生成 API 类型与控制器骨架
operator-sdk create api \
  --group apps \
  --version v1alpha1 \
  --kind AppService \
  --resource --controller

第一条命令执行后，SDK 会在当前目录生成 go.mod、Makefile、PROJECT、cmd/main.go、config/ 等文件；第二条命令则生成 api/v1alpha1/appservice_types.go、internal/controller/appservice_controller.go 以及对应的 CRD 与 RBAC 清单。注意 --resource 表示同时生成 CRD 资源定义，--controller 表示生成控制器，两者缺一不可。

二、目录结构解析

脚手架生成后，项目根目录下会出现若干关键目录，它们各自承担明确职责，理解它们的分工比记住文件名更重要。

api/v1alpha1/：存放 API 类型定义。appservice_types.go 中定义 AppServiceSpec（期望状态）与 AppServiceStatus（观测状态），并通过 +kubebuilder 标记生成 CRD 的 OpenAPI schema。
internal/controller/：存放控制器实现。appservice_controller.go 中的 Reconcile 方法是核心业务逻辑入口，SDK 已为你搭好 SetupWithManager 的注册框架。
cmd/main.go：程序入口。它负责解析启动参数、构建 Manager、注册 Scheme、挂载控制器与 Webhook，并启动 Manager 的事件循环。
config/：Kustomize 清单目录，按功能分层。config/crd 放 CRD，config/rbac 放权限，config/manager 放 Deployment，config/samples 放示例 CR，config/default 是聚合入口。
hack/：辅助脚本，如 boilerplate.go.txt 用于生成文件头版权声明。
PROJECT：SDK 的项目元数据文件，记录插件版本、API 列表、资源列表，后续 create api 会读取它来追加内容。

这里有一个容易混淆的点：api/ 与 internal/controller/ 是分离的。前者是“对外契约”，会被其他项目引用；后者是“内部实现”，不应被外部导入。这种分离让 API 类型可以独立演进，也符合 Go 的 internal 包可见性规则。

三、Makefile 工程化配置

Operator SDK 生成的 Makefile 是整套工程化的中枢，它把代码生成、编译、测试、镜像构建、部署、Bundle 打包全部串起来。常用目标如下：

目标	作用	典型使用场景
`make generate`	运行 controller-gen 生成 DeepCopy 方法	修改 API 类型后
`make manifests`	生成 CRD、RBAC、Webhook 清单	修改 kubebuilder 标记后
`make build`	编译 manager 二进制到 `bin/`	本地快速验证编译
`make test`	运行单元测试与 envtest 集成测试	提交前回归
`make docker-build`	构建 Operator 镜像	推送镜像前
`make deploy`	用 Kustomize 部署到集群	联调验证
`make bundle`	生成 OLM Bundle 目录	发布到 OperatorHub

Makefile 顶部定义了几个关键变量，理解它们才能按需定制：IMG 指定镜像地址，默认是 controller:latest，实际使用时应改为 quay.io/example/app-operator:v0.1.0；VERSION 控制 Bundle 版本；KUSTOMIZE、CONTROLLER_GEN 等工具版本由 Makefile 自动下载到 bin/，避免污染全局环境。若公司内网无法访问 GitHub，可通过 make kustomize 前设置代理，或手动把工具放入 bin/ 并跳过下载。

修改 API 类型后，务必先执行 make generate manifests，再执行 make build。否则 CRD 清单与代码不一致，部署到集群后会出现字段被裁剪（pruning）的问题。

四、脚手架数据流与工程化链路

下面这张图把“源码—生成物—构建产物—集群资源”之间的流转关系画出来，帮助你在修改任意一处时，快速判断需要触发哪条 make 链路。

从图中可以读出三条关键链路：第一条是“类型定义 → DeepCopy 生成”，只要改了 Spec 或 Status 字段，就必须重新 make generate；第二条是“标记 → CRD/RBAC 清单”，改了 +kubebuilder:validation 或 +kubebuilder:rbac 标记，就必须 make manifests；第三条是“源码 → 二进制 → 镜像 → 集群”，这是部署链路。三条链路互不替代，漏掉任何一条都会导致集群行为与预期不符。

五、初始化后的验证与常见问题

脚手架生成后，建议按以下顺序做一次最小验证：先执行 make generate manifests，确认无报错；再执行 make build，确认 bin/manager 生成；然后执行 make test，确认默认测试通过；最后用 make deploy IMG=quay.io/example/app-operator:v0.1.0 部署到测试集群，观察 kubectl get pods -n app-operator-system 是否 Running。

常见问题一：operator-sdk init 报“go.mod already exists”，说明当前目录已有 Go 模块，应换空目录或先清理。常见问题二：make manifests 报 controller-gen 下载失败，多为网络问题，可手动下载对应版本放入 bin/。常见问题三：部署后 CRD 字段被裁剪，通常是忘记执行 make manifests，导致集群中的 CRD 与代码不一致。