Kubernetes Cluster API 多集群生命周期管理实战
Cluster API（CAPI）使用 Kubernetes 风格 API 管理 Kubernetes 集群的创建、扩缩容、升级和删除。它将虚机、网络、负载均衡、控制面和节点定义为声明式资源，适合需要统一管理多套云上或私有云集群的平台团队。生产难点在管理集群、Provider 版本、证书、滚动升级、失败回滚和集群删除保护。
Cluster API 能自动创建和删除真实基础设施。错误的模板、OwnerReference 或 GitOps 变更可能批量替换节点甚至删除集群。生产必须启用审批、备份、权限隔离和分批变更。
一、核心架构
Management Cluster
├─ Cluster API Core Controller
├─ Bootstrap Provider（如 kubeadm）
├─ Control Plane Provider
└─ Infrastructure Provider（AWS/Azure/vSphere 等）
↓
Workload Clusters
管理集群保存期望状态并调用基础设施 API。Workload Cluster 承载业务。管理集群本身必须高可用、备份和受保护。
二、核心资源
Cluster：一套 Kubernetes 集群；Machine：单个节点的声明；MachineDeployment：类似 Deployment 的节点组；MachineSet：维护指定数量 Machine；KubeadmControlPlane：管理控制面节点和版本；- 基础设施资源：网络、虚机模板、负载均衡等；
ClusterClass：定义可复用集群拓扑模板。
资源通过引用和 OwnerReference 构成生命周期链。删除上层对象可能级联删除下层基础设施。
三、管理集群设计
生产管理集群应：
- 与普通业务隔离；
- 至少多控制面节点；
- 备份 etcd 和 CAPI 资源；
- 使用专用云凭证与最小权限；
- 监控 Controller 与 Webhook；
- 保留 Break Glass 访问；
- 防止 GitOps 误删除根 Cluster 对象；
- 明确自身升级与灾备流程。
Kind 适合实验或临时 Bootstrap，不适合作为长期生产管理集群。
四、Provider 体系
Infrastructure Provider 负责不同平台。选择前确认：
- 支持的 Kubernetes/CAPI 版本；
- 控制面、网络、LB 与存储能力；
- 升级路径和维护状态；
- 多可用区与故障域；
- MachineHealthCheck 与自动修复；
- 凭证模型和审计；
- 生产案例与社区活跃度。
Provider 不是可随意替换的驱动。它的 CRD Schema 和控制逻辑会影响现有集群。
五、Bootstrap 流程
典型做法：使用临时集群安装 Provider，创建永久管理集群，再用 clusterctl move 将 CAPI 对象迁移到永久管理集群。
迁移前必须：
- 新管理集群已安装兼容 Provider；
- 暂停并发变更；
- 备份源管理集群；
- 检查所有对象 Ready；
- 保证网络与凭证；
- 迁移后验证 Reconcile。
不要在 Move 过程中同时让 GitOps 在两个集群管理同一对象。
六、ClusterClass 与模板
ClusterClass 可定义标准控制面、节点组、网络和变量，为不同环境生成一致集群。
apiVersion: cluster.x-k8s.io/v1beta1
kind: Cluster
metadata:
name: prod-a
spec:
topology:
class: standard-ha
version: v1.34.0
controlPlane:
replicas: 3
workers:
machineDeployments:
- class: general
name: general
replicas: 5
版本示例仅说明结构，应选择 Provider 支持且经过验证的 Kubernetes 版本。
七、模板版本治理
修改共享 ClusterClass 可能影响多个集群。治理方式：
- ClusterClass 版本化；
- 变更先生成 Diff；
- 从测试集群和非关键集群灰度；
- 破坏性变更创建新 Class；
- 记录变量默认值变化；
- 建立集群到模板版本清单。
不要直接覆盖生产共享模板后等待所有集群自动收敛。
八、控制面高可用
控制面节点应跨故障域，负载均衡健康检查指向 API Server。需规划 etcd Quorum、证书、时间同步和升级顺序。
观察：
kubectl get kubeadmcontrolplane -A
kubectl get machines -A
kubectl describe kubeadmcontrolplane <name>
控制面扩容失败时检查基础设施资源、Bootstrap Data、云配额、LB 注册、kubeadm、证书和节点到 API Server 网络。
九、工作节点组
MachineDeployment 适合无状态节点组滚动更新。不同用途拆分节点组：通用、GPU、大内存、存储、系统组件。
升级/替换节点前确认：
- PodDisruptionBudget；
- 本地盘与 Local PV；
- DaemonSet；
- 容量余量；
- 最大不可用/激增；
- 云配额；
- 节点排空超时；
- 无法驱逐的 Pod。
十、版本升级
推荐顺序：
- 核对 CAPI/Core/Provider/Kubernetes 兼容矩阵；
- 备份管理集群；
- 升级 Provider 或按官方要求处理；
- 在测试集群升级控制面；
- 验证 API、etcd、CNI、CSI、CoreDNS；
- 灰度工作节点组；
- 再分批升级生产集群。
Kubernetes 不允许任意跨越多个小版本，Provider 也可能有额外限制。
十一、滚动替换原理
MachineDeployment 模板改变后会创建新 MachineSet，新增节点、加入集群、排空旧节点并删除旧基础设施。失败可能卡在：
- 新虚机无法创建；
- Bootstrap 未完成；
- 节点未注册；
- CNI 未 Ready；
- 排空受 PDB 阻塞；
- 旧实例删除失败。
排障沿资源链逐层看 Condition，而不是直接删除 Machine 重试。
十二、MachineHealthCheck
MachineHealthCheck 可根据节点 Condition 自动替换故障节点。配置过于激进会在控制面、CNI 或网络故障时批量删除健康虚机。
安全措施：
- 使用合理 Unhealthy Timeout；
- 设置最大不健康比例；
- 控制面与工作节点分别配置；
- 监控 Remediation；
- 在共享故障期间能够暂停；
- 有状态节点谨慎自动替换。
十三、节点自动扩缩容
Cluster Autoscaler 等组件可通过 MachineDeployment 副本范围扩缩容。需定义最小/最大容量、故障域、实例类型、标签和污点。
缩容前关注 Local PV、长终止任务、PDB 和系统 Pod。扩容慢可能是云配额、镜像、Bootstrap、IP 地址或 CNI 限制。
十四、凭证与权限
Provider 凭证通常能创建网络、虚机和负载均衡，属于高敏感权限。
- 每环境/账号隔离身份；
- 使用工作负载身份或短期凭证；
- Secret 加密与访问审计；
- 禁止业务 Namespace 读取 Provider Secret；
- 限制谁能创建/删除 Cluster；
- 监控凭证失败和异常资源创建。
十五、GitOps 集成
GitOps 可管理 Cluster/ClusterClass，但需防止：
- Prune 删除生产 Cluster；
- 两个控制源竞争；
- 模板改动同时波及全部集群；
- 删除保护与 Git 期望冲突；
- 凭证进入仓库。
建议生产 Cluster 删除使用人工确认，模板按批次晋级，状态与期望分离。
十六、删除集群
删除 Cluster 通常级联删除节点、负载均衡和网络资源。执行前：
- 确认业务与数据已迁移；
- 备份 etcd 和应用数据；
- 盘点云资源；
- 暂停 GitOps 重建；
- 确认外部依赖；
- 执行删除并跟踪 Finalizer；
- 验证残留和账单。
不要为解决 Terminating 直接移除 Finalizer，这会遗留真实基础设施。
十七、管理集群灾难恢复
备份内容：etcd、CAPI 对象、Provider CRD/版本、Secret、ClusterClass、Git 仓库、证书和云身份配置。
恢复方案可以是恢复原管理集群，或重建兼容管理集群后接管对象。必须避免两个管理集群同时 Reconcile 同一真实资源。定期在隔离环境演练恢复一个非关键 Workload Cluster 的管理能力。
十八、常见故障排查
Cluster 一直 Provisioning
检查 InfrastructureCluster、ControlPlane、Machine、Bootstrap Config 和 Provider 日志，找到第一个 False/Unknown Condition。
Machine 创建但节点不加入
检查 Cloud-init、kubeadm、证书、时间、DNS、API Server 地址、防火墙、CNI 和容器运行时。
升级卡住
检查 PDB、排空、MachineDeployment Strategy、云配额、健康检查和新节点 Ready。
Provider Controller 异常
暂停高风险变更，检查 Leader Election、Webhook、CRD、凭证、API 限流和版本兼容。
十九、监控指标
监控管理集群 API/etcd、Controller Reconcile、错误率、队列、Webhook、Cluster Ready、Machine 生命周期时长、失败 Machine、Remediation、升级进度、云 API 错误、配额和证书到期。
二十、上线清单
- 管理集群高可用、独立且已备份；
- Provider 与 Kubernetes 兼容矩阵明确；
- ClusterClass 版本化并分批变更；
- 控制面跨故障域；
- MachineHealthCheck 有最大影响限制；
- 节点替换经过 PDB、Local PV 和容量验证；
- GitOps 不会自动 Prune 生产集群；
- 删除流程含数据、云资源和账单检查；
- 管理集群恢复和 Provider 升级完成演练。
参考资料
- Cluster API Book：
https://main.cluster-api.sigs.k8s.io/introduction - clusterctl：
https://main.cluster-api.sigs.k8s.io/clusterctl/overview - ClusterClass：
https://main.cluster-api.sigs.k8s.io/tasks/experimental-features/cluster-class/