4. 环境准备：安装 kind、kubectl、clusterctl、Docker，配置本地开发集群
在开始使用 Cluster API 构建多租户控制面之前，必须搭建一套可复现的本地开发环境。本章将指导你完成所有核心工具的安装与验证，并最终启动一个本地 kind 集群作为 Cluster API 的管理集群。
4.1 工具链概览
本地开发环境由四个核心组件构成，它们各自承担不同的职责：
| 工具 | 版本要求 | 核心作用 | 安装方式 |
|---|---|---|---|
| Docker | ≥ 24.0 | 容器运行时，为 kind 提供节点容器 | 官方脚本 / 包管理器 |
| kind | ≥ 0.20 | 在 Docker 容器中运行本地 Kubernetes 集群 | 二进制下载 / go install |
| kubectl | 与目标集群版本偏差 ≤ 1 个 minor | 与 Kubernetes API 交互的命令行工具 | 二进制下载 / 包管理器 |
| clusterctl | ≥ 1.6 | Cluster API 生命周期管理 CLI | 二进制下载 / 官方脚本 |
版本对齐提示： 建议所有工具保持最新稳定版。clusterctl 1.6+ 对多租户特性（如跨命名空间 ClusterClass）有更好的支持。
4.2 安装步骤
4.2.1 Docker
kind 依赖 Docker 来运行节点容器。如果你尚未安装 Docker，请执行以下命令（以 Ubuntu 为例）：
# 卸载旧版本
sudo apt-get remove docker docker-engine docker.io containerd runc
# 安装依赖
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg
# 添加 Docker 官方 GPG 密钥
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
# 设置仓库
echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
$(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
# 安装 Docker Engine
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
# 验证安装
sudo docker run hello-world
权限配置： 如果不想每次使用 Docker 都加
sudo，请将当前用户加入 docker 组：sudo usermod -aG docker $USER，然后重新登录。
4.2.2 kind
kind（Kubernetes IN Docker）是本地集群的核心。推荐使用二进制安装：
# 下载最新版 kind
curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.23.0/kind-linux-amd64
# 赋予执行权限并移动到 PATH
chmod +x ./kind
sudo mv ./kind /usr/local/bin/kind
# 验证版本
kind version4.2.3 kubectl
kubectl 用于与集群交互。安装方式如下：
# 下载最新稳定版
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/kubectl
# 验证版本
kubectl version --client4.2.4 clusterctl
clusterctl 是 Cluster API 的官方 CLI。安装命令：
# 使用官方安装脚本
curl -L https://github.com/kubernetes-sigs/cluster-api/releases/download/v1.7.3/clusterctl-linux-amd64 -o clusterctl
# 赋予执行权限并移动
chmod +x clusterctl
sudo mv clusterctl /usr/local/bin/clusterctl
# 验证版本
clusterctl version4.3 配置本地开发集群
所有工具安装完成后，下一步是创建一个 kind 集群，它将作为 Cluster API 的 管理集群（Management Cluster）。
4.3.1 创建 kind 配置文件
为了支持 Cluster API 的多租户场景，建议在创建集群时暴露额外的端口映射，以便后续访问工作负载集群的 API Server。创建 kind-config.yaml：
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
name: capi-mgmt-cluster
nodes:
- role: control-plane
extraPortMappings:
- containerPort: 30443
hostPort: 30443
protocol: TCP
- containerPort: 30444
hostPort: 30444
protocol: TCP
- role: worker4.3.2 启动集群
kind create cluster --config kind-config.yaml
# 验证集群状态
kubectl cluster-info --context kind-capi-mgmt-cluster
kubectl get nodes4.3.3 验证 clusterctl 与集群的连通性
# 检查 clusterctl 能否识别当前集群
clusterctl config repositories
# 如果看到 provider 列表，说明环境准备成功
环境就绪检查清单：
docker info— Docker 守护进程运行中kind get clusters— 显示capi-mgmt-clusterkubectl get nodes— 至少 1 个 Ready 节点clusterctl version— 输出版本号无报错
4.4 环境架构示意
下图展示了本地开发环境中各组件之间的交互关系：
4.5 常见问题与避坑
- Docker 未启动： 执行
kind create cluster时报错Cannot connect to the Docker daemon。请先启动 Docker：sudo systemctl start docker。 - 端口冲突： 如果本地已占用 30443 或 30444 端口，kind 创建会失败。修改
kind-config.yaml中的hostPort为其他值。 - kubectl 版本偏差： 如果 kubectl 版本与 kind 集群的 Kubernetes 版本偏差超过 1 个 minor 版本，部分 API 调用可能失败。建议保持 kubectl 为最新稳定版。
- clusterctl 初始化失败： 如果
clusterctl init报错failed to get cluster，请确认当前 kubectl context 指向正确的 kind 集群：kubectl config use-context kind-capi-mgmt-cluster。
4.6 环境验证总结
完成上述步骤后，你的本地环境应满足以下条件：
| 验证项 | 预期结果 | 验证命令 |
|---|---|---|
| Docker 运行中 | 显示 Docker 版本和运行状态 | docker info |
| kind 集群存在 | 输出 capi-mgmt-cluster |
kind get clusters |
| kubectl 可访问集群 | 显示 2 个 Ready 节点 | kubectl get nodes |
| clusterctl 可用 | 输出 provider 仓库列表 | clusterctl config repositories |