📚 课程目录第4章 CAPI Provider架构

4. CAPI 安装与配置：使用 clusterctl 命令行工具、初始化管理集群、配置 Provider

本章是 CAPI 实践的起点。你将学习如何安装 clusterctl 命令行工具、初始化一个管理集群，并配置三种主流的基础设施 Provider：Docker（本地开发）、AWS（公有云）和 vSphere（私有云）。正确的安装与配置是后续多租户集群性能调优自动化的基石。

4.1 clusterctl 命令行工具安装

clusterctl 是 CAPI 的官方 CLI，用于管理集群生命周期、安装 Provider 和模板渲染。支持 Linux、macOS 和 Windows（WSL2）。

安装步骤（Linux / macOS）

下载二进制文件：从 GitHub Release 获取最新稳定版。
设置可执行权限：chmod +x ./clusterctl
移至 PATH 目录：sudo mv ./clusterctl /usr/local/bin/
验证安装：clusterctl version

# 示例：安装 v1.7.x 版本
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 version

版本对齐建议：确保 clusterctl 版本与目标 Kubernetes 版本兼容。生产环境建议使用 CAPI v1.7+ 以支持多租户和性能优化特性。

4.2 初始化管理集群

管理集群是运行 CAPI Controller 的 Kubernetes 集群。你可以使用 kind、kubeadm 或现有集群。以下以 kind 为例进行本地初始化。

步骤 1：创建 kind 集群

cat <<EOF | kind create cluster --name capi-mgmt --config=-
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
  extraPortMappings:
  - containerPort: 6443
    hostPort: 6443
    protocol: TCP
EOF

步骤 2：使用 clusterctl init 初始化

# 初始化管理集群，安装核心 CAPI 组件 + Docker Provider
clusterctl init --infrastructure docker

该命令会自动执行以下操作：

安装 cert-manager（证书管理）
安装 CAPI 核心控制器（cluster-api-controller）
安装指定的基础设施 Provider（如 Docker）
创建必要的 CRD 和 Webhook

  初始化验证：执行 clusterctl management-cluster status 查看所有 Provider 是否处于 Provisioned 状态。

4.3 配置基础设施 Provider

CAPI 通过 Provider 模式对接不同基础设施。下面分别介绍 Docker、AWS 和 vSphere Provider 的配置要点。

4.3.1 Docker Provider（本地开发与测试）

Docker Provider 使用 Docker 容器模拟节点，适合本地快速验证 CAPI 工作流，无需真实云资源。

配置项	说明	默认值
`DOCKER_HOST`	Docker 守护进程地址	`unix:///var/run/docker.sock`
`DOCKER_CONTROL_PLANE_MACHINE_COUNT`	控制平面节点数	`1`
`DOCKER_WORKER_MACHINE_COUNT`	工作节点数	`1`

# 使用 Docker Provider 生成工作负载集群 YAML
clusterctl generate cluster capi-quickstart \
  --flavor development \
  --kubernetes-version v1.28.0 \
  --control-plane-machine-count=1 \
  --worker-machine-count=1 \
  > capi-quickstart.yaml

4.3.2 AWS Provider（公有云生产环境）

AWS Provider 需要 AWS 凭证和 IAM 权限。推荐使用 clusterawsadm 工具自动创建 IAM 角色和策略。

安装 clusterawsadm：curl -L https://github.com/kubernetes-sigs/cluster-api-provider-aws/releases/... -o clusterawsadm
配置环境变量：设置 AWS_REGION、AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY
创建 IAM 角色：clusterawsadm bootstrap iam create-cloudformation-stack
初始化管理集群：clusterctl init --infrastructure aws

安全注意：AWS Provider 需要创建 EC2、VPC、ELB 等资源。建议使用最小权限 IAM 策略，并启用 CloudTrail 审计。生产环境务必使用临时凭证（如 IRSA 或 IAM Roles for Service Accounts）。

4.3.3 vSphere Provider（私有云 / 虚拟化环境）

vSphere Provider 允许 CAPI 在 vCenter 管理的虚拟化集群上创建和管理 Kubernetes 节点。

环境变量	说明	示例值
`VSPHERE_SERVER`	vCenter 地址	`vcenter.example.com`
`VSPHERE_USERNAME`	vCenter 用户名	`administrator@vsphere.local`
`VSPHERE_PASSWORD`	vCenter 密码	`your-password`
`VSPHERE_DATACENTER`	数据中心名称	`Datacenter`
`VSPHERE_DATASTORE`	数据存储名称	`datastore1`
`VSPHERE_NETWORK`	端口组名称	`VM Network`
`VSPHERE_RESOURCE_POOL`	资源池路径	`/Datacenter/host/Cluster/Resources`
`VSPHERE_FOLDER`	虚拟机文件夹	`/Datacenter/vm`
`VSPHERE_TEMPLATE`	VM 模板名称（用于克隆节点）	`ubuntu-2204-kube-v1.28.0`

# 初始化 vSphere Provider
export VSPHERE_SERVER="vcenter.example.com"
export VSPHERE_USERNAME="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="/Datacenter/vm"
export VSPHERE_TEMPLATE="ubuntu-2204-kube-v1.28.0"

clusterctl init --infrastructure vsphere

4.4 Provider 配置对比与选择

Provider	适用场景	资源开销	配置复杂度	性能调优空间
Docker	本地开发、CI/CD 测试、快速原型	低（容器级）	低	有限（受限于宿主机）
AWS	公有云生产、弹性伸缩、多区域	中高（EC2 实例）	中（需 IAM 配置）	高（实例类型、网络、存储）
vSphere	私有云、合规要求、已有 VMware 投资	中（VM 级别）	高（需 vCenter 权限）	高（资源池、DRS、存储策略）

4.5 多 Provider 共存与多租户基础

一个管理集群可以同时初始化多个 Provider，实现混合基础设施管理。例如：

# 同时初始化 Docker 和 AWS Provider
clusterctl init --infrastructure docker,aws

多 Provider 共存是 CAPI 多租户架构的基础。每个租户可以绑定不同的 Provider 和命名空间，实现资源隔离与性能隔离。

4.6 配置验证与故障排查

初始化完成后，使用以下命令验证配置是否正确：

# 查看所有 Provider 状态
clusterctl management-cluster status

# 查看 CAPI 相关 Pod
kubectl get pods -n capi-system
kubectl get pods -n capi-docker-system   # Docker Provider
kubectl get pods -n capi-aws-system      # AWS Provider
kubectl get pods -n capi-vsphere-system  # vSphere Provider

# 查看 CRD 是否注册
kubectl get crd | grep cluster.x-k8s.io

  常见问题：
  cert-manager 未就绪：检查镜像拉取策略，确保集群有外网访问权限。
Provider Pod CrashLoopBackOff：查看日志 kubectl logs -n capi-docker-system deployment/capi-docker-controller-manager，通常为凭证或网络配置错误。
vSphere Provider 连接失败：确认 VSPHERE_SERVER 可达，且 TLS 证书有效。

4.7 本章小结

clusterctl 是 CAPI 的单一入口工具，安装简单，版本需对齐。
管理集群初始化 自动安装核心组件和 Provider，支持多种基础设施。
Docker Provider 适合本地开发；AWS Provider 适合公有云生产；vSphere Provider 适合私有云。
多 Provider 共存是构建多租户集群性能调优自动化的基础设施前提。