3. CAPI 安装与配置：管理集群的搭建与 Provider 部署
本章是 CAPI 实践的基础。在部署工作负载集群之前，必须先搭建一个 管理集群（Management Cluster），并在其上安装 CAPI 核心组件及所需的 Provider。管理集群负责存储集群状态、协调资源并驱动工作负载集群的创建、升级与销毁。
3.1 管理集群（Management Cluster）概述
管理集群是一个标准的 Kubernetes 集群，它运行 CAPI 的控制器和 Provider。它可以是单节点集群（如 Kind、K3s），也可以是多节点生产集群。管理集群本身不运行用户业务负载，而是作为“集群的集群”存在。
| 角色 | 说明 | 典型实现 |
|---|---|---|
| 管理集群 | 运行 CAPI 控制器、Provider 和存储集群资源（Cluster、Machine、MachineDeployment 等 CRD） | Kind、K3s、EKS、AKS、GKE |
| 工作负载集群 | 由管理集群通过 CAPI 声明式创建和管理的目标集群 | 任意 Kubernetes 发行版 |
推荐实践： 在开发/测试环境中，使用 Kind 作为管理集群是最快的方式。Kind 集群运行在 Docker 容器中，启动快、资源占用低，且与 CAPI 的兼容性最好。
3.2 管理集群的搭建（以 Kind 为例）
以下步骤演示如何快速搭建一个 Kind 管理集群，并验证其可用性。
- 安装 Kind（如果尚未安装）
# 使用 brew（macOS）
brew install kind
# 使用 curl（Linux）
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- 创建 Kind 集群配置文件（可选，用于自定义端口映射和节点数）
# kind-cluster.yaml
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
extraPortMappings:
- containerPort: 6443
hostPort: 6443
protocol: TCP- 启动管理集群
kind create cluster --name capi-mgmt --config kind-cluster.yaml- 验证集群状态
kubectl cluster-info --context kind-capi-mgmt
kubectl get nodes
输出示例： 应看到
capi-mgmt-control-plane 节点处于 Ready 状态。
3.3 CAPI 命令行工具：clusterctl
clusterctl 是 CAPI 的官方 CLI 工具，用于安装、升级和管理 CAPI 组件。它封装了 Provider 的发现、下载和部署逻辑。
3.3.1 安装 clusterctl
# Linux / macOS
curl -L https://github.com/kubernetes-sigs/cluster-api/releases/download/v1.6.0/clusterctl-linux-amd64 -o clusterctl
chmod +x ./clusterctl
sudo mv ./clusterctl /usr/local/bin/clusterctl
# 验证安装
clusterctl version3.3.2 clusterctl 常用命令
| 命令 | 功能 | 示例 |
|---|---|---|
clusterctl init |
初始化管理集群，安装核心 CAPI 组件和指定 Provider | clusterctl init --infrastructure docker |
clusterctl generate cluster |
生成工作负载集群的 YAML 模板 | clusterctl generate cluster my-cluster --infrastructure docker > cluster.yaml |
clusterctl describe cluster |
查看集群的详细状态和资源拓扑 | clusterctl describe cluster my-cluster |
clusterctl upgrade plan |
检查可用的 CAPI 版本升级路径 | clusterctl upgrade plan |
clusterctl delete |
从管理集群中移除 CAPI 组件 | clusterctl delete --infrastructure docker |
3.4 Provider 的安装与配置
Provider 是 CAPI 的可插拔组件，负责与底层基础设施（如 AWS、vSphere、Docker）或特定功能（如 Kubeadm 引导）交互。安装 Provider 是 clusterctl init 的核心步骤。
3.4.1 Provider 类型
| Provider 类型 | 作用 | 常见实现 |
|---|---|---|
| Infrastructure Provider | 管理计算、网络、存储等基础设施资源 | AWS (CAPA), Azure (CAPZ), GCP (CAPG), vSphere (CAPV), Docker (CAPD) |
| Bootstrap Provider | 生成节点加入集群所需的引导令牌和配置 | Kubeadm (CABPK) |
| Control Plane Provider | 管理控制平面节点的生命周期 | Kubeadm (KCP), Talos (Sidero) |
3.4.2 安装 Docker Infrastructure Provider（CAPD）
CAPD 是 CAPI 的 Docker 基础设施 Provider，允许在本地 Docker 容器中创建工作负载集群，非常适合开发和测试。
# 初始化管理集群，安装核心 CAPI + Docker Provider
clusterctl init --infrastructure docker
# 查看安装的 Pod
kubectl get pods -n capi-system
kubectl get pods -n capd-system
注意： 安装 Provider 时，
clusterctl 会自动从 GitHub Release 下载对应的 Provider 镜像和 YAML 清单。确保管理集群可以访问 ghcr.io 和 registry.k8s.io。
3.4.3 配置 Provider 变量
某些 Provider 需要环境变量或 ConfigMap 来配置认证信息（如云厂商的 Access Key）。以 AWS 为例：
# 设置 AWS 凭证环境变量
export AWS_REGION=us-west-2
export AWS_ACCESS_KEY_ID=your-access-key
export AWS_SECRET_ACCESS_KEY=your-secret-key
# 初始化 AWS Provider
clusterctl init --infrastructure aws对于 Docker Provider，通常无需额外配置，但可以通过环境变量调整容器网络和镜像仓库：
export CAPI_DOCKER_IMAGE_TAG=v1.6.0
export CAPI_DOCKER_NETWORK=kind3.5 CAPI 组件架构图
下图展示了管理集群中 CAPI 核心组件与 Provider 的关系：
3.6 验证安装
安装完成后，通过以下命令验证 CAPI 组件是否正常运行：
# 查看 CAPI 相关的 CRD
kubectl get crd | grep cluster.x-k8s.io
# 查看 Provider 的 Deployment
kubectl get deployments -n capi-system
kubectl get deployments -n capd-system
# 查看 CAPI 版本
clusterctl version
快速验证： 运行
clusterctl init --infrastructure docker 后，如果所有 Pod 处于 Running 状态，说明管理集群和 Provider 安装成功。此时即可进入下一章：创建工作负载集群。
3.7 常见问题与排错
| 问题 | 可能原因 | 解决方案 |
|---|---|---|
clusterctl init 超时 |
网络无法访问 GitHub Release 或容器镜像仓库 | 配置代理或使用国内镜像源；检查 DNS 解析 |
Provider Pod 处于 CrashLoopBackOff |
缺少必要的环境变量或凭证 | 检查 Provider 文档，设置正确的环境变量（如 AWS_ACCESS_KEY_ID） |
| Kind 集群无法创建 | Docker 未运行或端口冲突 | 确保 Docker 服务运行；检查 6443 端口是否被占用 |