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

Operator SDK 是构建 Kubernetes Operator 的核心工具链，它封装了 controller-runtime、client-go 等底层库，提供脚手架生成、资源协调、测试框架等能力。本章将带你完成 SDK 安装、项目初始化，并深入解析生成的项目骨架，为后续编写单元测试奠定基础。

3.1 安装 Operator SDK

Operator SDK 支持多种安装方式，推荐使用 Homebrew（macOS/Linux） 或 直接下载二进制（Linux/macOS/Windows WSL）。以下为两种主流安装路径：

# 下载指定版本（以 v1.35.0 为例）
export ARCH=$(case $(uname -m) in x86_64) echo -n amd64 ;; aarch64) echo -n arm64 ;; esac)
export OS=$(uname | awk '{print tolower($0)}')
curl -LO https://github.com/operator-framework/operator-sdk/releases/download/v1.35.0/operator-sdk_${OS}_${ARCH}
chmod +x operator-sdk_${OS}_${ARCH}
sudo mv operator-sdk_${OS}_${ARCH} /usr/local/bin/operator-sdk

3.2 初始化 Operator 项目

Operator SDK 通过 init 命令创建项目骨架。以下步骤演示如何初始化一个名为 memcached-operator 的 Go 类型 Operator 项目：

1. 创建项目目录并进入：mkdir memcached-operator && cd memcached-operator
2. 初始化 Go 模块：go mod init github.com/example/memcached-operator
3. 运行 SDK init：

   operator-sdk init \
     --domain=example.com \
     --repo=github.com/example/memcached-operator \
     --language=go

4. 创建 API 和 Controller（可选，但推荐立即创建）：

   operator-sdk create api \
     --resource=true \
     --controller=true \
     --group=cache \
     --version=v1alpha1 \
     --kind=Memcached

3.3 项目结构深度解析

初始化完成后，项目目录结构如下。我们将逐层拆解每个文件/目录的作用：

memcached-operator/
├── .github/                  # GitHub Actions 工作流（可选）
├── config/
│   ├── crd/                  # CRD 定义（kustomize 格式）
│   ├── manager/              # Manager Deployment 配置
│   ├── rbac/                 # RBAC 权限（ServiceAccount, Role, RoleBinding）
│   └── samples/              # CR 示例 YAML
├── controllers/
│   └── memcached_controller.go  # 核心协调逻辑
├── api/
│   └── v1alpha1/
│       ├── memcached_types.go   # CRD 类型定义（Spec/Status）
│       ├── zz_generated.deepcopy.go  # 自动生成的 DeepCopy 方法
│       └── groupversion_info.go # API 组版本注册
├── internal/
│   └── controller/           # 内部控制器辅助逻辑（可选）
├── main.go                   # 程序入口，初始化 Manager
├── go.mod / go.sum           # Go 依赖管理
├── Makefile                  # 构建、测试、部署命令
├── PROJECT                   # Operator SDK 元数据文件
└── Dockerfile                # 容器镜像构建文件

3.4 项目核心组件关系图

下图展示了 Operator SDK 初始化后，各核心组件之间的调用与依赖关系：

3.5 关键文件详解：main.go 与控制器注册

main.go 是 Operator 的启动入口，其核心逻辑包括：

• 创建 Manager：通过 ctrl.NewManager(cfg, ctrl.Options{...}) 初始化，负责管理控制器、Webhook、Leader Election 等。
• 注册 Scheme：将自定义 API 类型（如 Memcached）添加到 runtime.Scheme，使 Manager 能识别 CRD 资源。
• 注册 Controller：调用 ctrl.NewControllerManagedBy(mgr).For(&cachev1alpha1.Memcached{}).Complete(reconciler) 将控制器绑定到 Manager。

// main.go 核心片段
func main() {
    mgr, err := ctrl.NewManager(ctrl.GetConfigOrDie(), ctrl.Options{
        Scheme:             scheme,
        MetricsBindAddress: ":8080",
        HealthProbeBindAddress: ":8081",
        LeaderElection:     false,
    })
    // ...
    if err = (&controllers.MemcachedReconciler{
        Client: mgr.GetClient(),
        Scheme: mgr.GetScheme(),
    }).SetupWithManager(mgr); err != nil {
        setupLog.Error(err, "unable to create controller", "controller", "Memcached")
        os.Exit(1)
    }
    // ...
}

3.6 控制器 Reconciler 结构

生成的 controllers/memcached_controller.go 包含 Reconciler 结构体及其 Reconcile 方法。这是单元测试的主要目标：

// controllers/memcached_controller.go
type MemcachedReconciler struct {
    client.Client
    Scheme *runtime.Scheme
}

func (r *MemcachedReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
    // 1. 获取 Memcached 实例
    // 2. 检查当前状态
    // 3. 调谐至期望状态（创建/更新/删除子资源）
    // 4. 更新状态
    return ctrl.Result{}, nil
}

3.7 项目元数据：PROJECT 文件

PROJECT 文件是 Operator SDK 的内部配置文件，记录了项目初始化参数。SDK 的后续命令（如 create api、generate）会读取此文件。其内容示例：

# PROJECT 文件
domain: example.com
layout:
- go.kubebuilder.io/v4
projectName: memcached-operator
repo: github.com/example/memcached-operator
version: "3"
plugins:
  manifests.sdk.operatorframework.io/v2: {}
  scorecard.sdk.operatorframework.io/v2: {}

理解 PROJECT 文件有助于排查脚手架生成问题，例如当 create api 失败时，可检查 domain 和 repo 是否与预期一致。

3.8 本章小结

通过本章学习，你应掌握：

• Operator SDK 的三种安装方式及版本验证方法。
• 使用 operator-sdk init 和 create api 初始化一个完整的 Operator 项目。
• 项目目录结构中每个文件/目录的职责，特别是 main.go、controllers/、api/ 的核心作用。
• Reconciler 结构体与 Reconcile 方法的基本形态，为后续编写单元测试建立上下文。