Cluster API：用 Kubernetes 声明式管理 Kubernetes 集群生命周期

痛点

管理多个 Kubernetes 集群时，运维团队常面临以下困境：

集群创建方式碎片化 — AWS 用 eksctl、GCP 用 gcloud、裸金属用 kubeadm，每种方式都有独立的工具链和工作流
Day-2 运维缺乏一致性 — 版本升级、节点扩缩容、安全补丁在不同环境用不同方式操作，极易出错
GitOps 难以覆盖基础设施层 — 应用部署已经 GitOps 化，但集群本身的生命周期管理仍依赖手动操作或各种脚本

Cluster API（CAPI）正是解决这个问题的 CNCF 项目 — 用 Kubernetes 的声明式模型来管理 Kubernetes 集群本身。

方案

Cluster API 的核心思路：把集群当作 Kubernetes 资源来管理。通过一个 Management Cluster 运行 CAPI 控制器，以 CRD 方式声明目标集群（Workload Cluster）的期望状态，控制器自动完成创建、升级、扩容等操作。

架构概览：

┌─────────────────────────────────────────┐
│         Management Cluster               │
│  ┌───────────────┐  ┌────────────────┐  │
│  │ CAPI Core     │  │ Infrastructure │  │
│  │ Controllers   │  │ Provider (AWS/ │  │
│  │               │  │ vSphere/Azure) │  │
│  └───────────────┘  └────────────────┘  │
│  ┌───────────────┐  ┌────────────────┐  │
│  │ Bootstrap     │  │ Control Plane  │  │
│  │ Provider      │  │ Provider       │  │
│  │ (kubeadm)     │  │ (kubeadm/EKS)  │  │
│  └───────────────┘  └────────────────┘  │
└─────────────────────────────────────────┘
            │ 管理
            ▼
┌───────────────────┐  ┌───────────────────┐
│ Workload Cluster A│  │ Workload Cluster B│
└───────────────────┘  └───────────────────┘

核心 CRD：

资源	作用
`Cluster`	集群的顶层抽象，定义网络、版本等
`Machine`	对应一个节点（VM/物理机）
`MachineSet`	管理一组相同配置的 Machine（类似 ReplicaSet）
`MachineDeployment`	Machine 的滚动更新策略（类似 Deployment）
`MachinePool`	利用云厂商托管节点组（如 ASG）

实操步骤

Step 1：准备 Management Cluster 并安装 clusterctl

# 安装 clusterctl CLI（v1.9+）
curl -L https://github.com/kubernetes-sigs/cluster-api/releases/latest/download/clusterctl-linux-amd64 -o clusterctl
chmod +x clusterctl && sudo mv clusterctl /usr/local/bin/

# 确认版本
clusterctl version

# 初始化 Management Cluster（以 AWS 为例）
# 先配置 AWS 凭证
export AWS_REGION=us-east-1
export AWS_ACCESS_KEY_ID=<your-key>
export AWS_SECRET_ACCESS_KEY=<your-secret>
export AWS_SESSION_TOKEN=<optional>

# 初始化 CAPI + AWS Provider
clusterctl init --infrastructure aws

初始化完成后，Management Cluster 中会部署 CAPI 核心控制器和 AWS 基础设施 Provider。

Step 2：生成 Workload Cluster 配置并创建

# 生成集群模板
export KUBERNETES_VERSION=v1.30.2
export CONTROL_PLANE_MACHINE_COUNT=3
export WORKER_MACHINE_COUNT=5
export AWS_CONTROL_PLANE_MACHINE_TYPE=m6i.xlarge
export AWS_NODE_MACHINE_TYPE=m6i.2xlarge

clusterctl generate cluster prod-cluster \
  --infrastructure aws \
  --kubernetes-version $KUBERNETES_VERSION \
  --control-plane-machine-count $CONTROL_PLANE_MACHINE_COUNT \
  --worker-machine-count $WORKER_MACHINE_COUNT \
  > prod-cluster.yaml

# 审核配置后应用
kubectl apply -f prod-cluster.yaml

# 监控集群创建进度
kubectl get cluster prod-cluster -o yaml
clusterctl describe cluster prod-cluster

生成的 YAML 是标准 Kubernetes 资源，可以直接纳入 Git 仓库用 ArgoCD/Flux 管理。

Step 3：获取 kubeconfig 并验证

# 等待集群 Ready
kubectl wait --for=condition=Ready cluster/prod-cluster --timeout=30m

# 获取 Workload Cluster 的 kubeconfig
clusterctl get kubeconfig prod-cluster > prod-cluster.kubeconfig

# 验证连接
kubectl --kubeconfig=prod-cluster.kubeconfig get nodes

Step 4：集群升级（滚动升级 Kubernetes 版本）

# 修改 KubeadmControlPlane 的版本字段
kubectl patch kubeadmcontrolplane prod-cluster-control-plane \
  --type merge \
  -p '{"spec":{"version":"v1.31.0"}}'

# 同步升级 Worker 节点
kubectl patch machinedeployment prod-cluster-md-0 \
  --type merge \
  -p '{"spec":{"template":{"spec":{"version":"v1.31.0"}}}}'

# 观察滚动升级进度
watch kubectl get machines

CAPI 会自动执行滚动升级：先创建新版本节点 → 等待就绪 → cordon + drain 旧节点 → 删除旧节点。整个过程零停机。

避坑指南

1. Management Cluster 本身的高可用

问题： Management Cluster 挂了，所有 Workload Cluster 的生命周期管理都会中断。

方案： - Management Cluster 至少 3 个 control plane 节点 - 定期用 clusterctl backup 备份 CAPI 资源 - 考虑用 clusterctl move 实现 Management Cluster 迁移 - Workload Cluster 运行不依赖 Management Cluster，只是管理操作会中断

2. Provider 版本兼容性矩阵

问题： CAPI Core 版本和 Infrastructure Provider 版本不匹配导致升级失败。

方案：

# 升级前检查兼容性
clusterctl upgrade plan

# 按推荐方案升级
clusterctl upgrade apply --contract v1beta1

始终参考 Provider 兼容性矩阵确认版本组合。

3. 节点引导失败排查

问题： Machine 一直卡在 Provisioning 状态，无法加入集群。

排查路径：

# 查看 Machine 状态和事件
kubectl describe machine <machine-name>

# 检查 Bootstrap 数据是否生成
kubectl get kubeadmconfig <config-name> -o yaml

# 查看 Infrastructure Provider 的日志
kubectl logs -n capi-system deploy/capi-controller-manager

# 检查云端实例的 cloud-init 日志（SSH 到实例）
cat /var/log/cloud-init-output.log

总结

Cluster API 让 Kubernetes 集群管理从"各厂商各搞一套"走向统一的声明式模型：

一致性 — 无论底层是 AWS、Azure、vSphere 还是裸金属，管理方式完全一致
GitOps Ready — 集群配置即代码，版本可追溯、变更可审计
自动化运维 — 版本升级、扩缩容都通过修改 YAML 声明式完成，控制器负责执行
适用场景 — 管理 5+ 集群的团队，或需要按需创建/销毁集群的平台团队

建议路径： 已有 2-3 个集群 → 搭建 Management Cluster → 用 clusterctl move 导入现有集群 → 逐步切换到 CAPI 管理。对于单集群场景，CAPI 的收益不大，eksctl/kubeadm 足矣。