2. Operator SDK 入门：安装、初始化与项目结构解析

Operator SDK 是构建 Kubernetes Operator 的官方脚手架工具，它封装了 controller-runtime、client-go 等底层库，提供项目初始化、代码生成、构建与测试等标准化流程。本章将带你完成 SDK 安装、创建第一个 Operator 项目，并深入解析项目目录结构与常用命令。

2.1 Operator SDK 安装

Operator SDK 支持 macOS、Linux 和 Windows（WSL2）环境。推荐使用 Homebrew（macOS）或直接下载二进制（Linux）。

操作系统 安装方式 命令 / 步骤
macOS Homebrew brew install operator-sdk
Linux (amd64) 下载二进制 
curl -LO https://github.com/operator-framework/operator-sdk/releases/download/v1.35.0/operator-sdk_linux_amd64
chmod +x operator-sdk_linux_amd64
sudo mv operator-sdk_linux_amd64 /usr/local/bin/operator-sdk
验证安装 版本检查 operator-sdk version
版本对齐提示： 本课程基于 Operator SDK v1.35.0 和 Go 1.22+。请确保你的 Go 版本 ≥ 1.21，否则项目初始化可能失败。

2.2 项目初始化：创建第一个 Operator

使用 operator-sdk init 命令初始化一个 Go 类型的 Operator 项目。以下步骤创建一个名为 memcached-operator 的示例项目：

  1. 创建项目目录并进入 
    mkdir memcached-operator && cd memcached-operator
  2. 初始化 Go module 和 Operator 骨架 
    operator-sdk init --domain=example.com --repo=github.com/example/memcached-operator
    • --domain：API 组的域名部分，例如 cache.example.com 中的 example.com。
    • --repo：Go module 路径，与 go.mod 中的 module 一致。
  3. 创建 API 和控制器 
    operator-sdk create api --group=cache --version=v1alpha1 --kind=Memcached --resource=true --controller=true
    • --group：API 组（不含域名），最终组名为 cache.example.com。
    • --kind：自定义资源类型，如 Memcached。
    • --resource 和 --controller：同时生成 CRD 类型定义和控制器骨架。
初始化后关键输出： 项目根目录下会生成 go.mod、main.go、api/、controllers/、config/ 等核心目录和文件。

2.3 项目结构解析

初始化后的 Operator 项目采用标准 Kubebuilder 布局，目录结构清晰，职责分离。下图展示了核心目录与文件的关系：

Operator SDK 项目目录结构 memcached-operator/ api/ controllers/ config/ internal/ v1alpha1/ memcached_types.go zz_generated.deepcopy.go memcached_controller.go suite_test.go crd/ manager/ rbac/ samples/ controller/ webhook/ main.go go.mod / go.sum Makefile Dockerfile api/ 定义 CRD 类型；controllers/ 实现调谐逻辑；config/ 包含部署 YAML；internal/ 存放内部工具。 main.go 是入口，Makefile 提供构建/测试/部署命令。

2.4 核心目录与文件详解

目录 / 文件 作用 关键内容
api/<version>/ 自定义资源（CRD）的 Go 类型定义 types.go 定义 Spec 和 Status；zz_generated.deepcopy.go 是自动生成的深拷贝方法
controllers/ 调谐（Reconcile）逻辑实现 xxx_controller.go 包含 Reconcile 方法；suite_test.go 是 envtest 集成测试
config/ Kubernetes 部署清单 crd/ 生成 CRD YAML；manager/ 部署 Operator 的 Deployment；rbac/ 权限规则；samples/ 示例 CR
internal/ 内部工具与辅助逻辑 controller/ 存放控制器选项；webhook/ 存放准入 Webhook 实现
main.go Operator 入口 初始化 Manager、注册 Scheme、启动控制器和 Webhook
Makefile 构建与部署自动化 包含 make manifests、make docker-build、make deploy 等目标

2.5 常用命令速查

Operator SDK 提供一组高频命令，覆盖开发、构建、测试和部署全流程。下表列出最常用的命令及其用途：

命令 用途 示例
operator-sdk init 初始化新 Operator 项目 operator-sdk init --domain=my.io --repo=my-operator
operator-sdk create api 创建 API（CRD + 控制器） operator-sdk create api --group=web --version=v1 --kind=App
make manifests 生成 CRD YAML 和 RBAC 清单 在项目根目录执行
make docker-build 构建 Operator 容器镜像 make docker-build IMG=my-registry/operator:latest
make deploy 将 Operator 部署到当前集群 make deploy IMG=my-registry/operator:latest
make test 运行单元测试和 envtest 集成测试 make test
operator-sdk cleanup 清理已部署的 Operator 资源 operator-sdk cleanup --name=my-operator
常见陷阱： 执行 make manifests 前，务必确保 api/ 下的类型定义已添加正确的 +kubebuilder:object:root=true 和 +kubebuilder:subresource:status 标记，否则 CRD 生成会缺失关键字段。

2.6 调谐循环与控制器工作流

Operator 的核心是调谐循环（Reconcile Loop）。下图展示了从事件触发到状态更新的完整流程：

Operator 调谐循环工作流 事件触发 Reconcile 请求入队 Reconcile 函数执行 读取当前状态 更新资源状态 返回 Requeue 或 nil Requeue 后重新入队
调谐要点： Reconcile 函数返回 ctrl.Result{Requeue: true} 或非 nil 错误时，请求会被重新入队，形成持续调谐。返回 ctrl.Result{} 表示调谐完成，不再重试。

2.7 本章小结

  • Operator SDK 通过 init 和 create api 快速搭建项目骨架。
  • 项目结构遵循 Kubebuilder 布局：api/ 定义类型，controllers/ 实现逻辑，config/ 存放部署清单。
  • 常用命令覆盖初始化、代码生成、构建镜像、部署和测试全流程。
  • 调谐循环是 Operator 的心脏，理解 Reconcile 入队、执行、状态更新和 Requeue 机制是后续调试的基础。
← 上一章 📖 返回目录 下一章 →