3. CAPI 安装与配置：使用 clusterctl 初始化管理集群、安装 AWS/Azure/vSphere Provider

本章将指导你完成 Cluster API（CAPI）管理集群的初始化，并安装主流基础设施 Provider（AWS、Azure、vSphere）。clusterctl 是 CAPI 官方 CLI 工具，负责管理集群生命周期、Provider 安装与版本控制。正确初始化管理集群是后续多集群变更门禁流水线的基础。

3.1 前置条件与环境准备

在安装 CAPI 之前，请确保管理集群满足以下条件：

3.2 安装 clusterctl CLI

下载并安装 clusterctl 二进制文件：

# Linux / macOS
curl -L https://github.com/kubernetes-sigs/cluster-api/releases/download/v1.7.0/clusterctl-linux-amd64 -o clusterctl
chmod +x clusterctl
sudo mv clusterctl /usr/local/bin/

# 验证安装
clusterctl version

3.3 初始化管理集群

使用 clusterctl init 命令初始化管理集群，安装核心组件和基础设施 Provider。核心组件包括 Cluster API 控制器管理器、Cluster API Bootstrap Provider（CABPK）和 Cluster API Control Plane Provider（KCP）。

# 初始化管理集群，安装 AWS Provider
clusterctl init --infrastructure aws

# 初始化管理集群，安装 Azure Provider
clusterctl init --infrastructure azure

# 初始化管理集群，安装 vSphere Provider
clusterctl init --infrastructure vsphere

3.4 Provider 配置与凭证管理

每个基础设施 Provider 需要对应的云凭证才能创建和管理资源。下表总结了三种 Provider 的凭证配置方式：

AWS Provider 凭证配置示例

# 创建 IAM 用户并获取 Access Key
export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
export AWS_REGION=us-west-2

# 生成 base64 编码的凭证
clusterctl generate cluster my-cluster --infrastructure aws \
  --target-namespace default \
  --flavor default > cluster.yaml

Azure Provider 凭证配置示例

# 创建服务主体并分配 Contributor 角色
az ad sp create-for-rbac --name "capi-sp" --role Contributor --scopes /subscriptions/{subscription-id}

# 设置环境变量
export AZURE_SUBSCRIPTION_ID="your-subscription-id"
export AZURE_TENANT_ID="your-tenant-id"
export AZURE_CLIENT_ID="your-client-id"
export AZURE_CLIENT_SECRET="your-client-secret"

vSphere Provider 凭证配置示例

# 设置 vCenter 连接信息
export VSPHERE_SERVER="vcenter.example.com"
export VSPHERE_USER="administrator@vsphere.local"
export VSPHERE_PASSWORD="your-password"
export VSPHERE_DATACENTER="Datacenter"
export VSPHERE_DATASTORE="datastore1"
export VSPHERE_NETWORK="VM Network"
export VSPHERE_RESOURCE_POOL="Resources"
export VSPHERE_FOLDER="vm"

3.5 验证初始化状态

初始化完成后，使用以下命令验证组件状态：

# 查看 CAPI 相关 Pod
kubectl get pods -n capi-system
kubectl get pods -n capi-webhook-system

# 查看 Provider 部署
kubectl get deployment -n capi-system
kubectl get deployment -n capi-webhook-system

# 查看 Provider 资源
kubectl get clusterclasses
kubectl get infrastructureproviders

3.6 CAPI 初始化架构图

下图展示了 clusterctl 初始化管理集群后的组件架构：

3.7 常见问题与排错

# 查看 CAPI 控制器日志
kubectl logs -n capi-system deployment/capi-controller-manager manager

# 查看 Provider 日志
kubectl logs -n capi-system deployment/capv-controller-manager manager

# 检查 Provider 版本
clusterctl describe provider

3.8 多 Provider 共存配置

在实际生产环境中，管理集群可能需要同时管理多个基础设施 Provider。使用 clusterctl init 可以一次性安装多个 Provider：

# 同时安装 AWS、Azure、vSphere Provider
clusterctl init --infrastructure aws,azure,vsphere

多 Provider 共存时，需要注意以下事项：

• 凭证隔离：每个 Provider 使用独立的 Secret 或环境变量，避免混淆。
• 资源命名：不同 Provider 的 CRD 资源名称不同（如 AWSCluster vs AzureCluster），不会冲突。
• 资源配额：确保管理集群有足够的资源运行多个 Provider 控制器。
• 网络策略：如果管理集群部署在受限网络，需要为每个 Provider 配置网络出口规则。

3.9 初始化后验证清单

完成初始化后，使用以下清单确认所有组件正常运行：

1. 核心组件：capi-controller-manager、capi-kubeadm-bootstrap-controller-manager、capi-kubeadm-control-plane-controller-manager 均处于 Running 状态。
2. Provider 组件：对应 Provider 控制器（如 capa-controller-manager、capz-controller-manager、capv-controller-manager）已部署并运行。
3. Webhook 服务：capi-webhook-service 和 Provider Webhook 服务正常响应。
4. CRD 注册：执行 kubectl get crd | grep cluster.x-k8s.io 确认核心 CRD 已注册。
5. Provider CRD：执行 kubectl get crd | grep infrastructure.cluster.x-k8s.io 确认 Provider CRD 已注册。
6. 集群模板：执行 clusterctl config cluster 测试能否生成集群模板。