3. 环境准备：安装核心工具链

在开始构建自定义 CRD 控制器之前，必须搭建一套完整、可复现的本地开发环境。本章将指导你依次安装 Go、Docker、kubectl 以及一个轻量级 Kubernetes 集群（minikube 或 kind）。

版本对齐建议：本课程所有示例均基于 Go 1.21+、Docker 24+、Kubernetes 1.28+ 以及 Operator SDK 1.34+。请尽量保持版本一致，避免因版本差异导致 API 变更或兼容性问题。

3.1 安装 Go 语言环境

Operator SDK 生成的控制器代码完全基于 Go 语言，且依赖 Go 模块系统进行依赖管理。Go 的安装方式因操作系统而异，但核心步骤一致。

3.1.1 下载与安装

  1. 访问 Go 官方下载页面，选择对应操作系统和架构的安装包。
  2. Linux/macOS 推荐使用 tar 解压至 /usr/local；Windows 直接运行 MSI 安装程序。
  3. 设置环境变量 GOPATH 和 PATH。
# Linux/macOS 示例
wget https://go.dev/dl/go1.21.5.linux-amd64.tar.gz
sudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf go1.21.5.linux-amd64.tar.gz
export PATH=$PATH:/usr/local/go/bin:$HOME/go/bin
echo 'export PATH=$PATH:/usr/local/go/bin:$HOME/go/bin' >> ~/.bashrc

3.1.2 验证安装

go version
# 期望输出: go version go1.21.5 linux/amd64
常见陷阱：如果 go version 显示旧版本，请检查 PATH 中是否包含其他 Go 安装路径。使用 which go 定位实际调用的二进制文件。

3.2 安装 Docker

Docker 用于构建和推送 Operator 镜像，同时也是 minikube 和 kind 运行集群的容器运行时。安装方式推荐使用官方脚本或系统包管理器。

操作系统 推荐安装方式 验证命令
Ubuntu/Debian sudo apt install docker.io docker --version
CentOS/RHEL sudo yum install docker-ce docker --version
macOS Docker Desktop for Mac docker --version
Windows Docker Desktop for Windows docker --version 
# 安装后，将当前用户加入 docker 组（Linux）
sudo usermod -aG docker $USER
newgrp docker

# 验证 Docker 能否正常运行
docker run hello-world
关键配置：确保 Docker 守护进程已启动（sudo systemctl enable --now docker），并且当前用户拥有执行 Docker 命令的权限。如果遇到权限拒绝，请检查是否已执行 usermod 并重新登录。

3.3 安装 kubectl

kubectl 是 Kubernetes 的命令行工具，用于与集群交互。Operator SDK 在生成、部署和调试过程中会频繁调用 kubectl。

3.3.1 安装步骤

# Linux (使用 curl 下载最新稳定版)
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
chmod +x kubectl
sudo mv kubectl /usr/local/bin/

# macOS (使用 Homebrew)
brew install kubectl

# Windows (使用 chocolatey)
choco install kubernetes-cli

3.3.2 验证与配置

kubectl version --client
# 期望输出: Client Version: v1.28.4

# 配置自动补全（可选但推荐）
echo 'source <(kubectl completion bash)' >> ~/.bashrc

3.4 安装本地 Kubernetes 集群

本地集群是开发和测试 CRD 控制器的核心环境。minikube 和 kind 是两种最流行的选择，各有优劣。

特性 minikube kind (Kubernetes in Docker)
底层技术 虚拟机或容器 Docker 容器作为节点
启动速度 较慢（需创建 VM） 快（秒级启动）
资源占用 较高 较低
多节点支持 支持 原生支持
适用场景 完整集群模拟 CI/CD、快速迭代

3.4.1 安装 minikube

# Linux
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
sudo install minikube-linux-amd64 /usr/local/bin/minikube

# macOS
brew install minikube

# 启动集群（默认驱动为 docker）
minikube start --cpus=4 --memory=8192 --kubernetes-version=v1.28.4

3.4.2 安装 kind

# Linux/macOS
curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.20.0/kind-linux-amd64
chmod +x ./kind
sudo mv ./kind /usr/local/bin/kind

# 创建集群配置文件
cat <<EOF > kind-config.yaml
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
- role: worker
- role: worker
EOF

# 启动集群
kind create cluster --config kind-config.yaml --name operator-dev
选择建议：如果你的机器内存小于 8GB，优先选择 kind；如果需要测试节点自动修复、存储卷挂载等高级特性，minikube 更合适。本课程后续示例同时兼容两种集群。

3.5 环境验证与架构总览

安装完成后，执行以下命令验证整个工具链是否就绪：

# 验证 Go
go version

# 验证 Docker
docker version

# 验证 kubectl
kubectl version --client

# 验证集群
kubectl cluster-info
kubectl get nodes

下图展示了本地开发环境中各工具之间的协作关系：

本地 Operator 开发环境架构 开发者工作站 Go 1.21+ Docker 24+ kubectl minikube kind 控制平面节点 工作节点 1 工作节点 2 Operator SDK 生成控制器代码 → 编译为容器镜像 → 部署到集群
环境就绪检查清单：
  • Go 版本 ≥ 1.21，GOPATH 和 PATH 正确配置
  • Docker 守护进程运行中，当前用户有执行权限
  • kubectl 版本与集群版本偏差在 ±1 个小版本内
  • minikube 或 kind 集群状态为 Running，kubectl get nodes 返回 Ready 节点

3.6 常见问题与排错

问题现象 可能原因 解决方案
go: command not found Go 未加入 PATH 检查 /usr/local/go/bin 是否在 PATH 中
Cannot connect to the Docker daemon Docker 服务未启动或权限不足 sudo systemctl start docker；将用户加入 docker 组
Unable to connect to the server kubectl 未找到集群上下文 检查 ~/.kube/config 是否存在；执行 kubectl config get-contexts
minikube 启动失败 驱动不支持或资源不足 使用 --driver=docker；增加内存/CPU 配额
kind 创建集群超时 镜像拉取慢或端口冲突 配置 Docker 镜像加速器；检查 localhost:6443 是否被占用
← 上一章 📖 返回目录 下一章 →