疯狂的SRE

深色模式

Cluster API 集群生命周期 ​

摘要：本文面向平台工程师，解释 Cluster API (CAPI) 如何用"以 K8s 管理 K8s"的声明式模型统一集群生命周期（创建、升级、扩缩、删除）。覆盖核心 CRD 分层、KubeadmControlPlane 滚动升级原理、infrastructure provider 差异、失败模式与生产边界。标注版本：Cluster API v1.12+（v1beta1 为主，部分资源 v1beta2），GA 自 v1.0（2021-10）。

适用版本与前提 ​

  • Cluster API：v1.12+（当前稳定线；v1beta1 为主 API，Cluster / KubeadmControlPlane 等部分资源引入 v1beta2）[版本相关]
  • 工具：clusterctl、一个已运行的 management cluster、目标云/虚拟化凭据
  • 前提：理解 K8s controller 协调循环与 kubeadm 基本流程

背景与问题 ​

在没有 CAPI 之前，集群交付通常是 kubeadm init + Terraform + Ansible + Wiki 的混合体：集群会漂移、升级像项目、销毁重建是半天 choreography。CAPI 的思路是：把集群本身当作 K8s 工作负载来管理——用声明式 YAML 描述"我要一个 3 控制面 + 5 工作节点的 v1.31 集群"，由控制器持续协调实际状态向期望状态收敛。

CAPI 由 SIG Cluster Lifecycle 维护，2021-10 发布 v1.0 达到生产可用，当前处于持续迭代阶段（v1.12 / v1.13 区间）。[版本相关：具体版本号以 cluster-api.sigs.k8s.io 发布页为准]

核心概念：四层资源模型 ​

CAPI 把集群生命周期拆成四类 CRD，每层各司其职：

层资源职责
集群定义Cluster顶层资源，引用基础设施与控制面 provider
基础设施AWSCluster / VSphereCluster / AWSMachine 等云平台相关：VPC、安全组、负载均衡、虚拟机
控制面KubeadmControlPlane (KCP)管理 apiserver / scheduler / controller-manager / etcd 数量与版本
节点Machine / MachineDeployment / MachineSet工作节点，镜像 Deployment/ReplicaSet 模式

架构与原理 ​

KubeadmControlPlane 的滚动升级 ​

KubeadmControlPlane (KCP) 是生产中最常用的控制面 provider。它维护 N 个控制面 Machine，并保证 etcd 法定人数（quorum）。当你修改 spec.version（如 v1.30 → v1.31），KCP 会逐节点滚动替换：每次替换一个控制面节点，等待其就绪并重新加入 etcd 集群后再处理下一个，从而保持奇数节点下的 quorum。

工作节点侧通过 MachineDeployment（spec.version + MachineTemplate）滚动升级，机制类似 Deployment 的 surge/rollout，可配置 strategy。[版本相关：具体 strategy 字段与默认值随 CAPI 小版本演进]

生产实践：一个完整集群定义 ​

以下为 v1beta1 的完整示例（AWS 场景，简化自官方文档，省略证书/SSH 细节）：

yaml
apiVersion: cluster.x-k8s.io/v1beta1
kind: Cluster
metadata:
  name: production-cluster
  namespace: default
spec:
  clusterNetwork:
    pods:
      cidrBlocks: ["192.168.0.0/16"]
    services:
      cidrBlocks: ["10.96.0.0/12"]
  controlPlaneRef:
    apiVersion: controlplane.cluster.x-k8s.io/v1beta1
    kind: KubeadmControlPlane
    name: production-control-plane
  infrastructureRef:
    apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
    kind: AWSCluster
    name: production-cluster
---
apiVersion: controlplane.cluster.x-k8s.io/v1beta1
kind: KubeadmControlPlane
metadata:
  name: production-control-plane
spec:
  replicas: 3
  version: v1.31.0
  machineTemplate:
    infrastructureRef:
      apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
      kind: AWSMachineTemplate
      name: control-plane-template
  kubeadmConfigSpec:
    clusterConfiguration:
      apiServer:
        extraArgs:
          audit-log-maxage: "30"
---
apiVersion: cluster.x-k8s.io/v1beta1
kind: MachineDeployment
metadata:
  name: production-workers
spec:
  clusterName: production-cluster
  replicas: 5
  selector:
    matchLabels: {}
  template:
    spec:
      clusterName: production-cluster
      version: v1.31.0
      bootstrap:
        configRef:
          apiVersion: bootstrap.cluster.x-k8s.io/v1beta1
          kind: KubeadmConfigTemplate
          name: worker-config
      infrastructureRef:
        apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
        kind: AWSMachineTemplate
        name: worker-template

实践建议

生产集群定义通常是 4–6 个 YAML（Cluster + 基础设施集群 + KCP + MachineDeployment + 各类 Template），建议纳入 Git 仓库做 GitOps 管理，使集群变更像应用代码一样可评审、可回滚。

操作步骤 ​

步骤 1：初始化 management cluster 并安装 provider ​

bash
# 安装 clusterctl
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/

# 以 AWS 为例初始化 CAPI 与其基础设施 provider
export AWS_B64ENCODED_CREDENTIALS=$(clusterawsadm bootstrap credentials encode-as-profile)
clusterctl init --infrastructure aws

步骤 2：应用集群定义并观察 ​

bash
kubectl apply -f production-cluster.yaml
clusterctl describe cluster production-cluster
# 取出新集群 kubeconfig
clusterctl get kubeconfig production-cluster > production.kubeconfig
kubectl --kubeconfig=production.kubeconfig get nodes

步骤 3：声明式升级 ​

bash
# 控制面逐节点滚动升级
kubectl patch kubeadmcontrolplane production-control-plane \
  --type merge -p '{"spec":{"version":"v1.32.0"}}'
# 工作节点随之升级
kubectl patch machinedeployment production-workers \
  --type merge -p '{"spec":{"template":{"spec":{"version":"v1.32.0"}}}}'
clusterctl describe cluster production-cluster

验证与回滚 ​

bash
# 验证各组件版本与节点就绪
kubectl --kubeconfig=production.kubeconfig get nodes
kubectl get kubeadmcontrolplane -o wide
# 回滚：将 version 改回原值即可，KCP/MD 会再次滚动协调
kubectl patch kubeadmcontrolplane production-control-plane \
  --type merge -p '{"spec":{"version":"v1.31.0"}}'

注意

跨多个 Kubernetes 次版本的"链式升级"（chained upgrade）在较新 CAPI 版本支持，但大跨度跳跃仍建议先在测试集群验证 etcd 与 kubelet 兼容性。切勿在业务高峰期执行跨次版本升级。[版本相关：chained upgrade 自 v1.12 引入，具体行为见 release notes]

Infrastructure Provider 差异 ​

CAPI 通过 provider 模型解耦平台差异。主流基础设施 provider：

Provider目标平台备注
CAPAAWS创建 EC2 / VPC / ELB
CAPZAzure创建 VM / VNet / LB
CAPVvSphere创建 VM / 资源池
CAPOOpenStack私有云
CAPDDocker (本地)开发/测试，生产不适用
Tinkerbell / Metal3裸金属物理机

Bootstrap provider 默认是 kubeadm，也支持 K3s / RKE2 / Talos 等。控制面 provider 除 KCP 外还有 KubeOne、K3s 等替代。

厂商特定

不同 provider 的 CRD 字段、配额限制、默认网络模型差异较大。例如 AWSCluster 需要 sshKeyName 与 VPC 规划，而 vSphereCluster 需要资源池与网络映射。迁移 provider 不等于"改个名字"——网络与存储模型需重新设计。[厂商特定]

失败模式与排障 ​

常用命令：

bash
kubectl get clusters,machines,machinedeployments -A
kubectl describe machine <name>            # 看事件与失败原因
kubectl logs -n capi-kubeadm-control-plane-system <kcp-controller>  # 控制面协调日志

安全与合规 ​

  • management cluster 自身必须 HA 且可备份：它一旦宕机，你将无法管理任何 workload cluster。许多团队把 management cluster 跑在托管 K8s（如 EKS/GKE）上，但这形成"用云管云"的依赖，需权衡。
  • 凭据（云 API key）通过 AWS_B64ENCODED_CREDENTIALS 等机制注入，应配合外部密钥管理，避免明文入 Git。

性能、容量与成本 ​

  • CAPI 控制器对单 management cluster 可管理的集群数量有上限（取决于 etcd 与控制器吞吐），大规模 fleet 需分片或多 management cluster。[版本相关/未实测：具体上限视版本与硬件，需按官方扩展指南压测]
  • 每个 workload cluster 有固定的控制面成本（3 控制面 VM + etcd）；小集群过多会抬高成本。

常见坑 ​

  • management cluster 未备份：灾难后无法重建对 workload cluster 的管理。
  • kubeadm 版本跳跃过大：跨多 minor 升级可能触发 etcd 数据格式 / API 弃用问题。
  • provider 凭证过期：云 token 失效导致 Machine 无法 provisioning。

替代方案与权衡 ​

方案适用不适用
Cluster API多平台统一生命周期、GitOps、自动化升级仅单一托管云、团队无 K8s 运维能力
托管 K8s (EKS/GKE/ACK)不想运维控制面需要跨云一致 API / 裸金属
Terraform + kubeadm已有 IaC 体系缺乏持续协调与声明式升级
Rancher RKE2想要一体化管理平面强 K8s 原生资源模型偏好

FAQ ​

Q：CAPI 适合只有两三个集群的团队吗？ A：通常过度。CAPI 引入 management cluster、provider 学习曲线与运维成本，小团队用托管 K8s + GitOps 更划算。

Q：能管理 management cluster 自己吗？ A：可以（self-hosted），但初始 bootstrap 仍需一个临时集群，且自管升级风险更高，需谨慎。

参考资料 ​

基于 VitePress 构建 · 托管于阿里云 ECS

Copyright © 2026 CrazySRE