📚 课程目录第2章 CAPI基础概念

多集群变更门禁的流水线集成与CAPI联动 - 第2节

2.1 Cluster API 核心资源模型

Cluster API (CAPI) 的核心设计哲学是“声明式集群生命周期管理”。它将 Kubernetes 集群本身视为一种可编程的基础设施资源，通过一组自定义资源定义（CRD）来抽象集群的各个组成部分。理解这些核心资源是掌握 CAPI 联动与多集群变更门禁的基础。

2.1.1 三大核心资源概览

资源名称	作用域	核心职责	类比（传统运维）
Cluster	管理集群（Management Cluster）	定义集群的全局元数据、网络、负载均衡器及关联的 Infrastructure 和 ControlPlane 模板	VM 或物理机的“主机定义”
Machine	目标集群（Workload Cluster）	代表集群中的一个节点（控制平面或工作节点），绑定具体的 Infrastructure 实例（如 EC2）	一台具体的服务器实例
MachineDeployment	目标集群（Workload Cluster）	管理一组同质 Machine 的滚动更新、扩缩容和自愈，类似 Deployment 管理 Pod	Auto Scaling Group + 滚动更新策略

关键认知： Cluster 是“蓝图”，Machine 是“实例”，MachineDeployment 是“控制器”。在变更门禁流水线中，我们通常通过修改 MachineDeployment 的模板来触发滚动更新，从而实现对工作节点集群的无损变更。

2.1.2 Cluster 资源深度解析

Cluster 资源是 CAPI 的顶层入口。它不直接管理节点，而是通过引用两个关键对象来定义集群的“骨架”：

InfrastructureRef：指向一个 Provider 特定的基础设施模板（如 AWSCluster、AzureCluster），用于定义 VPC、子网、安全组等。
ControlPlaneRef：指向控制平面资源（如 KubeadmControlPlane），用于定义 API Server、Controller Manager 等组件的配置。

apiVersion: cluster.x-k8s.io/v1beta1
kind: Cluster
metadata:
  name: prod-cluster-01
spec:
  clusterNetwork:
    services:
      cidrBlocks: ["10.96.0.0/12"]
    pods:
      cidrBlocks: ["192.168.0.0/16"]
    serviceDomain: "cluster.local"
  infrastructureRef:
    apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
    kind: AWSCluster
    name: prod-cluster-01-aws
  controlPlaneRef:
    apiVersion: controlplane.cluster.x-k8s.io/v1beta1
    kind: KubeadmControlPlane
    name: prod-cluster-01-cp

2.1.3 Machine 与 MachineDeployment 的关系

Machine 是单一节点的抽象。而 MachineDeployment 则提供了声明式的管理能力，是生产环境中管理工作节点的首选方式。其核心字段 spec.template.spec 定义了 Machine 的模板，包括基础设施模板引用（InfrastructureRef）和引导数据（Bootstrap）。

  流水线集成点： 在变更门禁场景中，流水线通常不直接操作 Machine，而是通过 kubectl patch machinedeployment 修改其 spec.template.spec 中的镜像版本或启动脚本，CAPI 控制器会自动创建新的 Machine 并逐步替换旧的 Machine，实现滚动更新。

apiVersion: cluster.x-k8s.io/v1beta1
kind: MachineDeployment
metadata:
  name: prod-worker-md-0
  namespace: default
spec:
  clusterName: prod-cluster-01
  replicas: 3
  selector:
    matchLabels:
      nodepool: worker
  template:
    spec:
      clusterName: prod-cluster-01
      version: v1.28.5
      bootstrap:
        configRef:
          apiVersion: bootstrap.cluster.x-k8s.io/v1beta1
          kind: KubeadmConfigTemplate
          name: prod-worker-bootstrap
      infrastructureRef:
        apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
        kind: AWSMachineTemplate
        name: prod-worker-mt

2.2 Provider 模型：基础设施与引导的抽象

CAPI 的 Provider 模型是其可扩展性的基石。它将“集群是什么”与“集群运行在哪里”解耦。Provider 分为两大类：

Infrastructure Provider：负责管理底层基础设施，如 AWS、Azure、vSphere、OpenStack 等。它们提供具体的 InfrastructureMachineTemplate 和 InfrastructureCluster 资源。
Bootstrap Provider：负责生成节点启动所需的配置（如 kubeadm join 命令、证书等）。最常用的是 Kubeadm Bootstrap Provider。

注意： 在流水线集成中，如果你需要更换云厂商或调整节点初始化脚本，你只需要更换对应的 Infrastructure Provider 和 Bootstrap Provider 的模板引用，而 Cluster 和 MachineDeployment 的抽象逻辑保持不变。这是 CAPI 实现多云统一管理的关键。

2.3 核心资源关系图

下图展示了 Cluster、MachineDeployment、Machine 以及 Provider 之间的引用关系。注意 MachineDeployment 通过模板间接引用 Infrastructure 和 Bootstrap 资源。

2.4 资源生命周期与变更门禁的关联

在流水线集成中，理解资源的创建与更新顺序至关重要。下表总结了关键操作对应的 CAPI 资源变更：

流水线阶段	操作对象	CAPI 响应行为	门禁检查点
集群创建	Cluster + ControlPlane + MachineDeployment	异步创建基础设施、控制平面节点、工作节点	检查 Cluster 的 Ready 状态
工作节点升级	MachineDeployment.spec.template	创建新 Machine，等待 Ready 后删除旧 Machine	检查 MachineDeployment 的 UpdatedReplicas
扩缩容	MachineDeployment.spec.replicas	增加或减少 Machine 数量	检查 MachineDeployment 的 ReadyReplicas
基础设施替换	InfrastructureMachineTemplate	更新 MachineDeployment 引用的模板，触发滚动更新	验证新模板的实例类型或镜像

最佳实践： 在变更门禁流水线中，建议将 MachineDeployment 的 spec.strategy 设置为 RollingUpdate，并配置合理的 maxSurge 和 maxUnavailable 参数，以确保在滚动更新期间业务不中断。

2.5 多集群管理中的资源隔离

当管理多个集群时，CAPI 通过 Namespace 和 标签选择器 实现资源隔离。每个 Cluster 及其关联的 Machine、MachineDeployment 通常位于同一个 Namespace 中。流水线在操作时，必须明确指定目标集群的 Namespace 和集群名称，避免跨集群误操作。

# 查看指定集群的所有 Machine
kubectl get machine -n team-alpha -l cluster.x-k8s.io/cluster-name=prod-cluster-01

# 更新指定集群的 MachineDeployment 镜像版本
kubectl set image machinedeployment/prod-worker-md-0 \
  -n team-alpha \
  '*=registry.example.com/k8s-worker:v1.29.0'

这种基于 Namespace 的隔离机制，使得同一个管理集群可以安全地托管开发、测试、生产等多个工作负载集群，而变更门禁流水线只需在流水线参数中传递 --namespace 和 --cluster-name 即可实现精准控制。