2. Operator SDK 入门：安装、配置与核心架构

Operator SDK 是构建 Kubernetes Operator 的官方脚手架工具，它封装了 controller-runtime、client-go 等底层库，提供项目初始化、代码生成、测试与打包等全生命周期能力。本章将带你完成 SDK 的安装与配置，初始化第一个 Operator 项目，并深入理解其核心——Reconcile 循环。

2.1 Operator SDK 的安装与配置

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

2.1.1 安装方式对比

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.36.1/operator-sdk_${OS}_${ARCH}
chmod +x operator-sdk_${OS}_${ARCH}
sudo mv operator-sdk_${OS}_${ARCH} /usr/local/bin/operator-sdk

2.1.2 环境依赖检查

• Go 语言环境： go version 确认版本 ≥ 1.21。
• Kubernetes 集群： 可使用 kind、minikube 或远程集群，kubectl cluster-info 确认连接正常。
• Docker / Podman： 用于构建 Operator 镜像，docker version 确认运行中。

2.2 项目初始化

使用 operator-sdk init 命令创建 Operator 项目骨架。以下以创建一个名为 memcached-operator 的项目为例，管理 Memcached 集群。

2.2.1 初始化命令

mkdir -p $HOME/projects/memcached-operator
cd $HOME/projects/memcached-operator
operator-sdk init --domain=example.com --repo=github.com/example/memcached-operator

• --domain：自定义资源的 API 组后缀，例如 cache.example.com。
• --repo：Go module 路径，用于依赖管理。

2.2.2 初始化后的项目结构

2.3 理解 Operator 的基本架构：Reconcile 循环

Operator 的核心是一个事件驱动的控制循环，称为 Reconcile 循环。它持续监听集群中自定义资源（CR）实例的变化，并将实际状态调整为期望状态。

2.3.1 Reconcile 循环的工作流程

1. 事件触发： CR 被创建、更新或删除时，Informer 将事件入队。
2. Reconcile 请求： controller-runtime 从队列中取出请求，调用用户实现的 Reconcile 方法。
3. 读取当前状态： 通过 Kubernetes API 读取 CR 实例及关联资源（如 Pod、Service）。
4. 对比期望状态： 根据 CR 的 Spec 字段计算期望状态。
5. 执行调和操作： 创建、更新或删除资源，使实际状态趋近期望状态。
6. 更新状态： 将调和结果写入 CR 的 Status 字段。
7. 返回结果： 返回 ctrl.Result{}（成功）或 error（重试）。

2.3.2 Reconcile 方法签名

每个控制器必须实现 Reconcile 方法，其标准签名如下：

import (
  "context"
  ctrl "sigs.k8s.io/controller-runtime"
  "sigs.k8s.io/controller-runtime/pkg/client"
)

func (r *MemcachedReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
  // 1. 获取 CR 实例
  var memcached cachev1.Memcached
  if err := r.Get(ctx, req.NamespacedName, &memcached); err != nil {
    return ctrl.Result{}, client.IgnoreNotFound(err)
  }

  // 2. 调和逻辑：确保 Deployment 副本数等于 CR 的 Spec.Size
  // ...

  // 3. 更新 CR 状态
  memcached.Status.ReadyReplicas = currentReplicas
  if err := r.Status().Update(ctx, &memcached); err != nil {
    return ctrl.Result{}, err
  }

  return ctrl.Result{}, nil
}

2.3.3 控制器与 Manager 的关系

Manager 是 Operator 的“大脑”，负责管理多个控制器、Webhook 和缓存。每个控制器注册到 Manager 后，由 Manager 统一启动和协调。

2.4 本章小结

• Operator SDK 通过 init 命令快速生成项目骨架，包含 main.go、controllers/、api/ 等核心目录。
• Reconcile 循环是 Operator 的“心脏”，遵循“事件 → 读取 → 对比 → 调和 → 更新”的闭环。
• Manager 统一管理多个控制器和共享组件，确保资源访问的一致性和效率。
• Reconcile 方法必须幂等，避免副作用；返回 ctrl.Result{Requeue: true} 可实现定时重试。