3. 初始化 Operator 项目：使用 Operator SDK 创建项目骨架与目录结构解析

在开始编写自定义资源（CRD）和协调逻辑之前，首先需要搭建一个标准的 Operator 项目骨架。Operator SDK 提供了 init 命令，能够快速生成符合 Kubebuilder 布局的项目结构，避免手动配置 Go Module、RBAC 规则和 Webhook 样板代码。

3.1 前置环境检查

执行初始化前，请确认以下工具已正确安装并可用：

工具	最低版本	验证命令
Go	1.21+	go version
Operator SDK CLI	1.35+	operator-sdk version
kustomize	v5.0+	kustomize version
Docker	24+	docker version

3.2 创建项目骨架

使用 operator-sdk init 命令初始化一个基于 Go 的 Operator 项目。以下命令会在当前目录下生成完整的项目骨架：

mkdir memcached-operator && cd memcached-operator
operator-sdk init \
  --domain=example.com \
  --repo=github.com/example/memcached-operator \
  --plugins=helm/v1

参数说明：

• --domain：CRD 的 API 组后缀，例如 cache.example.com。
• --repo：Go Module 路径，与 go.mod 中的 module 名称一致。
• --plugins：指定 Operator 类型，常用值包括 helm/v1、ansible/v1、go/v3。本课程以 Go 类型为主，后续章节会切换为 go/v3。

3.3 项目目录结构全景

初始化完成后，项目根目录下会生成以下文件和文件夹。理解每个目录的职责是后续开发的基础。

memcached-operator/
├── Dockerfile
├── Makefile
├── PROJECT
├── config/
│   ├── crd/
│   ├── rbac/
│   ├── manager/
│   ├── samples/
│   └── scorecard/
├── controllers/
├── api/
├── main.go
├── go.mod
├── go.sum
└── hack/
    └── boilerplate.go.txt

目录/文件	职责说明
main.go	Operator 入口，初始化 Manager、注册 Controller 与 Webhook。
config/	Kubernetes 资源清单（CRD、RBAC、Deployment、Prometheus 等）。
controllers/	协调逻辑（Reconcile 函数）存放目录，每个 CRD 对应一个 Controller 文件。
api/	自定义资源（CRD）的 Go 类型定义，包括 types.go 和 zz_generated.deepcopy.go。
Dockerfile	多阶段构建镜像，用于将 Operator 编译并打包为容器镜像。
Makefile	常用任务入口：构建、测试、部署、生成 CRD 清单等。
PROJECT	Operator SDK 元数据文件，记录项目名称、域名、插件版本等信息。
hack/	代码生成模板（如 boilerplate.go.txt 版权头）。

3.4 核心文件详解

3.4.1 main.go — 程序入口

main.go 是 Operator 的启动点，主要完成以下工作：

• 初始化 ctrl.Manager，配置 Metrics 端口、健康检查端点、LeaderElection。
• 注册 Controller 到 Manager。
• 注册 Webhook（如果启用）。
• 启动 Manager 的事件循环。

// main.go 核心片段（简化）
func main() {
    mgr, err := ctrl.NewManager(ctrl.GetConfigOrDie(), ctrl.Options{
        Scheme:             scheme,
        MetricsBindAddress: ":8080",
        LeaderElection:     true,
        LeaderElectionID:   "3d7e4f2c.example.com",
    })
    if err != nil {
        setupLog.Error(err, "unable to start manager")
        os.Exit(1)
    }

    if err = (&controllers.MemcachedReconciler{
        Client: mgr.GetClient(),
        Scheme: mgr.GetScheme(),
    }).SetupWithManager(mgr); err != nil {
        setupLog.Error(err, "unable to create controller")
        os.Exit(1)
    }

    if err := mgr.Start(ctrl.SetupSignalHandler()); err != nil {
        setupLog.Error(err, "problem running manager")
        os.Exit(1)
    }
}

3.4.2 config/ 目录 — Kubernetes 资源清单

config/ 下按功能拆分子目录，每个子目录包含多个 YAML 文件，最终由 kustomize 合并部署：

子目录	包含内容
crd/	CRD 的 YAML 定义（由 make generate 自动生成）。
rbac/	ServiceAccount、Role、ClusterRole、RoleBinding。
manager/	Operator Deployment 和 Service 定义。
samples/	CR 示例 YAML，用于快速测试。
scorecard/	Operator Scorecard 测试配置。

3.4.3 PROJECT 文件 — 元数据仓库

PROJECT 文件是 Operator SDK 的内部状态文件，记录了项目初始化时的参数。后续执行 operator-sdk create api 或 operator-sdk create webhook 时会读取此文件。

# PROJECT 文件示例
domain: example.com
layout:
- helm.sdk.operatorframework.io/v1
projectName: memcached-operator
repo: github.com/example/memcached-operator
version: "3"

3.5 项目初始化流程（SVG 图）

下图展示了从环境检查到项目骨架生成的整体流程，以及各步骤产出的关键文件：

3.6 初始化后的关键操作

项目骨架生成后，建议立即执行以下验证步骤，确保环境配置正确：

1. 检查 Go 模块依赖：go mod tidy 下载所有依赖并清理无用包。
2. 编译验证：make build 编译 Operator 二进制文件，确认无语法错误。
3. 生成 CRD 清单：make generate 生成 DeepCopy 方法和 CRD YAML（需先创建 API）。
4. 本地运行测试：make run 在本地启动 Operator，连接当前 kubeconfig 指向的集群。

3.7 常见初始化问题排查

问题现象	可能原因	解决方案
command not found: operator-sdk	CLI 未安装或不在 PATH 中	下载二进制并执行 chmod +x && mv /usr/local/bin
go: module ... not found	Go Proxy 未配置或网络不通	设置 GOPROXY=https://goproxy.cn,direct
Error: failed to create project	目录非空或权限不足	使用空目录执行 init，或检查写权限
kustomize not found	kustomize 未安装	go install sigs.k8s.io/kustomize/kustomize/v5@latest

3.8 本章小结

通过 operator-sdk init 命令，我们快速搭建了一个符合 Kubebuilder 标准的 Operator 项目骨架。项目目录结构清晰分离了 API 定义、协调逻辑、Kubernetes 资源清单和构建脚本。理解 main.go、config/、controllers/ 和 api/ 的职责，是后续添加 CRD 和编写 Reconcile 逻辑的基础。下一阶段将使用 operator-sdk create api 添加自定义资源定义，并生成对应的 Controller 框架。