📚 课程目录第4章 CAPI工作负载集群创建

4. CAPI 工作负载集群创建：使用 ClusterClass 定义集群模板、创建第一个工作负载集群、集群状态检查与故障排查

本章是 CAPI 实践的核心环节。我们将从 ClusterClass 模板定义开始，逐步创建第一个工作负载集群，并掌握集群状态检查与常见故障的排查方法。ClusterClass 是 CAPI v1beta1 引入的关键抽象，它允许平台团队将集群的拓扑结构（ControlPlane、Worker、基础设施）定义为可复用的模板，从而标准化集群创建流程。

4.1 ClusterClass：集群模板的核心抽象

ClusterClass 是一种集群范围的资源，它定义了一个集群的“蓝图”。它通过引用多个 WorkerClass 和 ControlPlaneClass 来组合出完整的集群拓扑。使用 ClusterClass 可以显著降低创建和管理大量相似集群的复杂度。

  核心概念： ClusterClass 将集群的“形状”（拓扑）与“实例”（具体集群）分离。你只需定义一次模板，后续创建集群时只需指定 ClusterClass 名称和必要的变量即可。

4.1.1 ClusterClass 资源结构

一个典型的 ClusterClass 资源包含以下关键字段：

字段	说明	示例值
`spec.controlPlane`	定义控制面的模板引用（如 KubeadmControlPlane）	`ref: apiVersion: controlplane.cluster.x-k8s.io/v1beta1 kind: KubeadmControlPlaneTemplate`
`spec.workers`	定义工作节点池的模板列表（MachineDeploymentClass）	`machineDeployments: [class: "default-worker"]`
`spec.infrastructure`	定义集群基础设施的模板（如 AWSClusterTemplate）	`ref: apiVersion: infrastructure.cluster.x-k8s.io/v1beta2 kind: AWSClusterTemplate`
`spec.variables`	定义可配置的变量，用于在创建集群时注入差异	`variables: [name: "region", required: true]`

4.1.2 定义第一个 ClusterClass

以下是一个基于 AWS 的 ClusterClass 示例，它定义了一个包含 1 个控制面节点和 1 个默认工作节点池的集群模板。

apiVersion: cluster.x-k8s.io/v1beta1
kind: ClusterClass
metadata:
  name: quick-start-aws
spec:
  controlPlane:
    ref:
      apiVersion: controlplane.cluster.x-k8s.io/v1beta1
      kind: KubeadmControlPlaneTemplate
      name: aws-cp-template
  infrastructure:
    ref:
      apiVersion: infrastructure.cluster.x-k8s.io/v1beta2
      kind: AWSClusterTemplate
      name: aws-cluster-template
  workers:
    machineDeployments:
    - class: default-worker
      template:
        spec:
          clusterName: "{{ .cluster.name }}"
          template:
            spec:
              bootstrap:
                dataSecretName: "{{ .bootstrap.dataSecretName }}"
              infrastructureRef:
                apiVersion: infrastructure.cluster.x-k8s.io/v1beta2
                kind: AWSMachineTemplate
                name: aws-worker-template
  variables:
    - name: region
      required: true
      schema:
        openAPIV3Schema:
          type: string
          default: "us-east-1"
    - name: controlPlaneMachineType
      required: false
      schema:
        openAPIV3Schema:
          type: string
          default: "t3.medium"

最佳实践： 将 ClusterClass 视为“集群的 API 版本”。通过版本化管理 ClusterClass，你可以实现集群模板的灰度升级和回滚。

4.2 创建第一个工作负载集群

有了 ClusterClass 模板，创建集群变得非常简洁。你只需要创建一个 Cluster 资源，并指定其 topology 字段引用 ClusterClass。

4.2.1 使用 ClusterClass 创建集群

以下 YAML 定义了一个名为 my-workload-cluster 的集群，它基于 quick-start-aws 模板，并覆盖了 region 变量。

apiVersion: cluster.x-k8s.io/v1beta1
kind: Cluster
metadata:
  name: my-workload-cluster
  namespace: default
spec:
  topology:
    class: quick-start-aws
    version: v1.28.0
    variables:
      - name: region
        value: "eu-west-1"
    workers:
      machineDeployments:
        - class: default-worker
          name: worker-pool-0
          replicas: 3

应用该 YAML 后，CAPI 控制器会自动根据 ClusterClass 模板实例化所有底层资源（ControlPlane、MachineDeployments、基础设施对象）。

4.2.2 创建流程可视化

下图展示了从提交 Cluster 资源到集群就绪的完整流程。

4.3 集群状态检查

集群创建后，需要持续监控其状态。CAPI 提供了丰富的状态字段和事件来反映集群的健康状况。

4.3.1 关键状态字段

使用 kubectl get cluster my-workload-cluster -o yaml 可以查看集群的完整状态。以下是最重要的状态字段：

状态字段	说明	健康值示例
`status.phase`	集群生命周期阶段	`Provisioned` (已就绪)
`status.controlPlaneReady`	控制面是否就绪	`true`
`status.infrastructureReady`	基础设施是否就绪	`true`
`status.conditions`	详细的条件列表，包含类型、状态、原因和消息	`Ready=True, Reason=ClusterProvisioned`

4.3.2 常用检查命令

查看集群列表及状态： kubectl get cluster -A
查看集群详细状态： kubectl describe cluster my-workload-cluster
查看集群事件： kubectl get events --field-selector involvedObject.kind=Cluster,involvedObject.name=my-workload-cluster
查看 Machine 状态： kubectl get machine -l cluster.x-k8s.io/cluster-name=my-workload-cluster

快速健康检查： 使用 kubectl get cluster -o wide 可以同时看到集群的 PHASE、CONTROLPLANE 和 WORKERS 状态，一目了然。

4.4 故障排查

集群创建失败时，需要系统性地排查问题。以下是最常见的故障场景及排查方法。

4.4.1 常见故障场景与排查步骤

故障现象	可能原因	排查命令/方法
集群 `phase` 卡在 `Provisioning`	基础设施资源创建失败（如 AWS 配额不足）	`kubectl describe cluster` 查看 `conditions`；检查对应基础设施提供者的日志
控制面节点未就绪	KubeadmControlPlane 模板配置错误	`kubectl get kubeadmcontrolplane -n <namespace>`； `kubectl describe machine <machine-name>`
工作节点池无法扩容	MachineDeployment 模板或 bootstrap 数据问题	`kubectl get machinedeployment`； `kubectl logs -n capi-system deployment/capi-controller-manager`
集群创建后无法访问	kubeconfig 未正确生成或网络不通	`clusterctl get kubeconfig my-workload-cluster`；检查安全组/网络 ACL

4.4.2 排查流程可视化

下图展示了一个系统化的故障排查决策流程。

4.4.3 关键日志查看

当上述步骤无法定位问题时，需要查看 CAPI 控制器的日志：

# 查看 CAPI 控制器日志
kubectl logs -n capi-system deployment/capi-controller-manager --tail=100

# 查看基础设施提供者日志（以 AWS 为例）
kubectl logs -n capa-system deployment/capa-controller-manager --tail=100

# 查看特定集群的协调日志（通过标签过滤）
kubectl logs -n capi-system deployment/capi-controller-manager --tail=200 | grep "my-workload-cluster"

注意： 如果集群创建后长时间处于 Provisioning 状态，请检查基础设施提供者的资源配额（如 AWS EC2 实例限制、VPC 子网 IP 耗尽等）。这是最常见的“卡住”原因。

4.5 本章小结

通过本章的学习，你已经掌握了：

ClusterClass 的核心概念与资源结构，以及如何定义可复用的集群模板。
使用 ClusterClass 创建第一个工作负载集群的完整流程。
集群状态检查的关键字段和常用命令。
系统化的故障排查流程，包括常见场景、排查步骤和日志查看方法。