3. 项目初始化：使用 operator-sdk init 创建项目、理解项目目录结构、Go Module 管理

本章是实战的起点。我们将使用 operator-sdk init 命令创建一个标准的 Kubernetes Operator 项目骨架，并深入剖析其目录结构。理解每个文件和目录的职责，是后续开发、调试与本地运行的基础。同时，我们也会介绍 Operator SDK 如何利用 Go Module 管理依赖，确保项目构建的可复现性。

3.1 使用 operator-sdk init 创建项目

在开始之前，请确保你已经安装了 operator-sdk CLI 工具（版本 ≥ 1.25.0），并且配置好了 Go 语言环境（版本 ≥ 1.21）。我们将创建一个名为 memcached-operator 的项目，用于管理 Memcached 集群。

# 检查 operator-sdk 版本
operator-sdk version

# 检查 Go 版本
go version

执行以下命令初始化项目：

# 创建项目目录并进入
mkdir memcached-operator
cd memcached-operator

# 初始化项目，使用 Go 语言，指定 API 组和版本
operator-sdk init \
  --domain=example.com \
  --repo=github.com/example/memcached-operator \
  --language=go

参数说明：

• --domain: 自定义资源的 API 组域名，例如 cache.example.com。
• --repo: Go Module 的路径，通常对应你的代码仓库地址。
• --language=go: 指定使用 Go 语言开发（默认值）。

命令执行成功后，控制台会输出类似以下信息：

Writing kustomize manifests for you to edit...
Writing scaffold for you to edit...
Get controller runtime:
  go get sigs.k8s.io/controller-runtime@v0.15.0
Update dependencies:
  go mod tidy
Next: define a resource with:
  operator-sdk create api

3.2 项目目录结构详解

初始化完成后，项目根目录下会生成以下标准结构。理解每个组件的用途是高效开发的关键。

memcached-operator/
├── .github/               # GitHub Actions 工作流配置（CI/CD）
├── config/                # Kubernetes 资源清单（Kustomize）
│   ├── crd/               # 自定义资源定义（CRD）的 YAML
│   ├── manager/           # Operator Deployment 和 ServiceAccount
│   ├── rbac/              # RBAC 权限（ClusterRole, ClusterRoleBinding）
│   ├── samples/           # 自定义资源（CR）的示例 YAML
│   └── default/           # Kustomize 的 kustomization.yaml（组合所有资源）
├── controllers/           # 控制器逻辑（Reconcile 循环）
│   └── memcached_controller.go
├── api/                   # API 类型定义（Go 结构体）
│   └── v1alpha1/
│       ├── memcached_types.go
│       ├── groupversion_info.go
│       └── zz_generated.deepcopy.go
├── hack/                  # 辅助脚本（如 code-generator）
├── main.go                # Operator 入口文件
├── go.mod                 # Go Module 定义
├── go.sum                 # 依赖校验文件
├── Makefile               # 构建、测试、部署命令
├── PROJECT                # 项目元数据（Operator SDK 使用）
└── Dockerfile             # 容器镜像构建文件

关键目录与文件职责对照表：

3.3 项目初始化流程与组件关系

下图展示了 operator-sdk init 命令执行后，生成的各个组件之间的逻辑关系与数据流向。

3.4 Go Module 管理与依赖解析

Operator SDK 项目使用标准的 Go Module 进行依赖管理。初始化命令会自动执行 go mod tidy，下载并锁定核心依赖，如 controller-runtime、client-go 和 kubebuilder 相关库。

核心依赖文件：

• go.mod: 定义模块路径（module github.com/example/memcached-operator）和所有直接依赖的版本。
• go.sum: 记录每个依赖版本的哈希值，用于校验下载文件的完整性，防止依赖篡改。

module github.com/example/memcached-operator

go 1.21

require (
    k8s.io/apimachinery v0.28.0
    k8s.io/client-go v0.28.0
    sigs.k8s.io/controller-runtime v0.15.0
)

依赖管理最佳实践：

3.5 项目初始化后的下一步

项目骨架创建完成后，下一步是使用 operator-sdk create api 命令添加自定义资源（CRD）和控制器。这个命令会进一步在 api/ 和 controllers/ 目录下生成具体的类型定义和 Reconcile 模板代码，为后续的业务逻辑开发做好准备。