2. 开发环境搭建：Go版本选择、依赖管理（go mod）、安装kubebuilder、搭建本地Kind集群

搭建一个稳定、可复现的开发环境是调试控制面控制器的第一步。本章将指导你完成从 Go 版本选择到本地 Kind 集群启动的全流程，确保后续章节的调试操作拥有统一的基础设施。

2.1 Go 版本选择与安装

Controller Runtime 项目对 Go 版本有明确要求。选择错误的版本可能导致编译失败或运行时行为异常。

安装完成后，验证 Go 环境：

go version
# 期望输出: go version go1.22.x linux/amd64 (或 darwin/arm64)

go env GOPATH
# 确保 GOPATH 已设置，通常为 $HOME/go

2.2 依赖管理：go mod 最佳实践

Kubernetes 生态的依赖关系复杂，go mod 是官方推荐的依赖管理工具。以下是在控制器项目中管理依赖的核心步骤。

2.2.1 初始化模块

mkdir my-controller && cd my-controller
go mod init github.com/your-org/my-controller

2.2.2 添加核心依赖

手动添加 sigs.k8s.io/controller-runtime 及其传递依赖：

go get sigs.k8s.io/controller-runtime@v0.17.3
go get sigs.k8s.io/controller-tools@v0.14.0  # 用于代码生成
go get k8s.io/client-go@v0.29.0               # 与集群交互的客户端

2.2.3 依赖版本锁定

执行 go mod tidy 清理无用依赖，并生成 go.sum 文件锁定版本：

go mod tidy

2.3 安装 kubebuilder

kubebuilder 是构建 Kubernetes 控制器的脚手架工具，它集成了 controller-runtime、controller-tools 和 envtest。

2.3.1 下载与安装

# 下载最新稳定版本 (v3.x)
curl -L -o kubebuilder "https://go.kubebuilder.io/dl/latest/$(go env GOOS)/$(go env GOARCH)"
chmod +x kubebuilder && sudo mv kubebuilder /usr/local/bin/

# 验证安装
kubebuilder version
# 期望输出: version: "v3.14.x"

2.3.2 初始化项目脚手架

kubebuilder init --domain my-domain.io --repo github.com/your-org/my-controller

该命令会生成以下目录结构：

my-controller/
├── cmd/
│   └── main.go          # 控制器入口
├── config/
│   ├── crd/             # CRD 定义
│   ├── rbac/            # RBAC 配置
│   └── manager/         # 控制器部署配置
├── internal/
│   └── controller/      # 控制器逻辑
├── Dockerfile
├── Makefile
├── go.mod
└── go.sum

2.4 搭建本地 Kind 集群

Kind (Kubernetes in Docker) 可以在本地快速启动轻量级集群，非常适合开发调试。

2.4.1 安装 Kind

# Linux / macOS
curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.22.0/kind-$(uname)-amd64
chmod +x ./kind && sudo mv ./kind /usr/local/bin/kind

# 验证
kind version
# 期望输出: kind v0.22.0 go1.22.x linux/amd64

2.4.2 创建集群配置文件

创建一个 kind-config.yaml 文件，配置端口映射以便本地调试：

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
  extraPortMappings:
  - containerPort: 30080   # NodePort 范围
    hostPort: 30080
    protocol: TCP
  kubeadmConfigPatches:
  - |
    kind: InitConfiguration
    nodeRegistration:
      kubeletExtraArgs:
        node-labels: "ingress-ready=true"

2.4.3 启动集群

kind create cluster --name controller-dev --config kind-config.yaml

# 验证集群状态
kubectl cluster-info --context kind-controller-dev
kubectl get nodes

2.5 环境验证：运行一个最小控制器

完成上述步骤后，通过以下命令验证整个开发环境是否正常工作：

# 编译控制器
go build -o bin/manager cmd/main.go

# 将 kubeconfig 指向 Kind 集群
export KUBECONFIG=$(kind get kubeconfig-path --name controller-dev)

# 运行控制器 (前台模式)
./bin/manager --metrics-bind-address=:8080 --health-probe-bind-address=:8081

如果控制台输出类似以下日志，说明环境搭建成功：

I0101 12:00:00.000000       1 leaderelection.go:250] attempting to acquire leader lease...
I0101 12:00:00.100000       1 leaderelection.go:260] successfully acquired lease

2.6 开发环境架构总览

下图展示了本地开发环境中各组件之间的关系：

2.7 环境清单核对表

完成本章所有步骤后，请使用下表核对你的开发环境是否完整：