📚 课程目录第4章 Operator SDK安装与初始化

4. Operator SDK 安装与初始化：环境要求、安装 Operator SDK、创建第一个 Operator 项目骨架

本章是动手实践的第一站。在编写任何自定义控制器或 CRD 之前，必须先搭建 Operator SDK 开发环境，并理解项目骨架的结构。我们将依次完成：环境依赖检查、SDK 安装、项目初始化，以及骨架目录的逐层解析。

4.1 环境要求与依赖检查

Operator SDK 本质上是一个脚手架工具，它依赖宿主机的 Go 运行时、Kubernetes 集群访问权限以及容器镜像构建工具。下表列出了最低版本要求与推荐版本：

依赖项	最低版本	推荐版本	用途
Go	1.21	1.22+	编译 Operator 二进制与测试
Kubernetes 集群	1.25	1.28+	部署与调试 Operator
kubectl	1.25	与集群版本匹配	与集群交互
Docker / Podman	20.10	24+	构建 Operator 镜像
make	4.0	4.3+	执行 Makefile 目标
git	2.30	2.40+	版本管理与代码拉取

检查清单：在终端中依次执行 go version、kubectl version --client、docker --version 确认版本号。如果使用 Kind 或 Minikube 作为本地集群，请确保集群已启动且 kubectl cluster-info 返回正常。

4.2 安装 Operator SDK

Operator SDK 提供多种安装方式。对于云原生开发者，推荐使用 二进制安装 或 Go 工具链安装。以下为两种主流方式：

4.2.1 方式一：二进制安装（跨平台）

# Linux / macOS (x86_64)
export ARCH=$(case $(uname -m) in x86_64) echo -n amd64 ;; aarch64) echo -n arm64 ;; esac)
export OS=$(uname | awk '{print tolower($0)}')
export OPERATOR_SDK_VERSION=v1.36.1

curl -LO "https://github.com/operator-framework/operator-sdk/releases/download/${OPERATOR_SDK_VERSION}/operator-sdk_${OS}_${ARCH}"

# 验证 SHA256 校验和（可选但推荐）
curl -LO "https://github.com/operator-framework/operator-sdk/releases/download/${OPERATOR_SDK_VERSION}/checksums.txt"
sha256sum --check checksums.txt --ignore-missing

# 安装到系统路径
chmod +x operator-sdk_${OS}_${ARCH} && sudo mv operator-sdk_${OS}_${ARCH} /usr/local/bin/operator-sdk

4.2.2 方式二：Go 工具链安装（需已安装 Go）

go install github.com/operator-framework/operator-sdk/cmd/operator-sdk@v1.36.1

版本锁定：本课程基于 Operator SDK v1.36.1。不同大版本之间的项目骨架结构、API 组版本、Makefile 目标可能存在差异。请务必使用 operator-sdk version 确认安装后的版本号。

4.3 创建第一个 Operator 项目骨架

安装完成后，使用 operator-sdk init 命令初始化一个 Go 类型的 Operator 项目。该命令会生成完整的项目骨架，包括 Go Module、Makefile、Kustomize 配置以及默认的控制器入口。

4.3.1 初始化命令

# 创建项目目录并进入
mkdir -p my-first-operator && cd my-first-operator

# 初始化 Go module 项目
operator-sdk init \
  --domain=example.com \
  --repo=github.com/myuser/my-first-operator \
  --language=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.18.0
# Update dependencies:
#   go mod tidy
# Next: define a resource with:
#   operator-sdk create api

4.3.2 骨架目录结构

初始化完成后，项目根目录下会生成以下核心文件与目录：

my-first-operator/
├── .github/              # GitHub Actions 工作流模板
├── cmd/
│   └── main.go           # Operator 主入口，启动 Manager
├── config/
│   ├── crd/              # 自定义资源定义（Kustomize base）
│   ├── default/          # 默认的 Kustomize overlay
│   ├── manager/          # Manager Deployment 与 Service
│   ├── rbac/             # RBAC 权限配置
│   └── samples/          # CR 示例 YAML
├── hack/
│   └── boilerplate.go.txt # 文件头模板
├── internal/
│   └── controller/       # 控制器逻辑（后续创建）
├── Dockerfile            # 多阶段构建镜像
├── Makefile              # 构建、测试、部署目标
├── PROJECT               # 项目元数据（SDK 内部使用）
├── go.mod                # Go Module 定义
├── go.sum                # 依赖校验文件
└── main.go               # 主入口（软链接或实际文件）

  关键文件速览：
  main.go — 初始化 Manager、注册 Scheme、启动控制器循环。
Makefile — 封装了 make build、make docker-build、make deploy 等常用目标。
config/default — 包含 Kustomize 的 kustomization.yaml，用于一键部署所有资源。
PROJECT — 记录项目域名、仓库地址、API 版本等元数据，SDK 后续命令依赖此文件。

4.4 项目骨架架构图

下图展示了初始化后 Operator 项目的核心组件及其关系。理解这张图有助于后续添加 API 和控制器时定位代码位置。

4.5 验证项目骨架

初始化完成后，建议执行以下验证步骤，确保环境与骨架均正常工作：

编译检查：在项目根目录执行 make build，应生成二进制文件 bin/manager。
代码生成检查：执行 make generate，确保无错误输出。
Kustomize 配置检查：执行 make kustomize 安装 kustomize，然后 kustomize build config/default 应输出完整的 Kubernetes 资源清单。
单元测试：执行 make test，默认测试应全部通过。

常见问题：如果 make build 失败，请检查 go version 是否 ≥ 1.21，并确认 go mod tidy 已成功执行。如果 kustomize build 报错，可能是 config/default/kustomization.yaml 中引用了不存在的资源，检查路径是否正确。

4.6 小结

本章完成了 Operator SDK 的安装与项目初始化。你已掌握：

环境依赖的版本要求与检查方法。
两种主流安装方式（二进制与 Go 工具链）。
使用 operator-sdk init 创建项目骨架。
骨架目录结构及其核心文件的作用。
验证项目骨架是否可编译、可部署。