2. Cluster API 核心概念回顾：Cluster、Machine、MachineDeployment、MachineSet 资源模型与 API 设计哲学
在深入查询优化与样本留存之前，必须重新审视 Cluster API（CAPI）的四个核心资源模型。这些资源不仅是声明式集群生命周期的基石，其 API 设计哲学也直接决定了查询模式、索引策略与数据留存边界。本节从资源定义、关系拓扑与设计意图三个维度进行回顾。
2.1 核心资源模型一览
| 资源名称 | API 版本（典型） | 作用域 | 核心职责 | 是否直接管理计算实例 |
|---|---|---|---|---|
| Cluster | cluster.x-k8s.io/v1beta1 | Namespace | 定义集群拓扑、基础设施提供商、控制面与网络配置 | 否 |
| Machine | cluster.x-k8s.io/v1beta1 | Namespace | 表示一台工作节点或控制面节点的期望状态与当前状态 | 是（通过基础设施模板） |
| MachineDeployment | cluster.x-k8s.io/v1beta1 | Namespace | 声明式管理一组同质 Machine 的滚动更新、扩缩容与自愈 | 间接（通过 MachineSet） |
| MachineSet | cluster.x-k8s.io/v1beta1 | Namespace | 保证指定数量的 Machine 副本运行，支持原地升级与回滚 | 间接（通过 Machine） |
关键区分：Machine 是“原子单元”，直接映射到一台虚拟机或裸金属实例；MachineDeployment 与 MachineSet 是“编排单元”，负责副本管理与版本控制。Cluster 是“聚合根”，持有全局拓扑与提供商引用。
2.2 资源关系拓扑与所有权链
四个资源之间通过 ownerReferences 与 cluster.x-k8s.io/cluster-name 标签形成严格的所有权树。理解这一拓扑是设计高效查询与样本留存策略的前提。
所有权链（自上而下）：
Cluster → MachineDeployment → MachineSet → Machine → InfrastructureMachine（如 AWSMachine / GCPMachine）
Cluster → MachineDeployment → MachineSet → Machine → InfrastructureMachine（如 AWSMachine / GCPMachine）
以下 SVG 图展示了核心资源之间的层级关系与标签传递路径：
2.3 API 设计哲学：声明式、分层与可组合
Cluster API 的设计哲学可以归纳为三个核心原则，这些原则直接影响查询优化策略：
- 声明式终态驱动：用户通过
spec描述期望状态，控制器通过status报告当前状态。查询必须区分spec字段（如spec.replicas）与status字段（如status.readyReplicas），避免全量拉取。 - 分层抽象与关注点分离：Cluster 层不关心 Machine 细节，MachineDeployment 不直接管理基础设施。这种分层使得查询可以按层级裁剪——例如只查询
status.phase为Failed的 Machine，而不必遍历整个集群。 - 可组合性与模板化：MachineDeployment 通过
spec.template.spec引用 Machine 模板，Machine 通过spec.infrastructureRef引用基础设施模板。这种组合模式要求查询时支持跨资源引用解析，对索引设计提出挑战。
2.4 关键字段与查询关注点
| 资源 | 关键查询字段 | 查询优化关注点 |
|---|---|---|
| Cluster | status.phase, spec.infrastructureRef, spec.controlPlaneRef |
按阶段过滤、关联控制面与基础设施提供商 |
| Machine | status.phase, status.nodeRef, spec.clusterName, metadata.labels |
按生命周期阶段、节点关联、集群标签过滤 |
| MachineDeployment | spec.replicas, status.readyReplicas, spec.template.spec.version |
按副本状态、Kubernetes 版本过滤 |
| MachineSet | spec.replicas, status.availableReplicas, metadata.ownerReferences |
按可用副本数、所属 MachineDeployment 过滤 |
常见陷阱：直接对
status.phase 做字符串匹配时，注意 Pending、Provisioning、Running、Deleting、Failed 等阶段之间的转换路径。查询 Failed 状态的 Machine 时，应同时检查 status.failureReason 与 status.failureMessage 以获取根因。
2.5 设计哲学对查询优化的启示
从 API 设计哲学出发，可以推导出以下查询优化原则：
- 按层级裁剪：优先在 Cluster 级别过滤，再下钻到 MachineDeployment 或 MachineSet，避免全量扫描。
- 利用标签索引：Cluster API 控制器自动为资源添加
cluster.x-k8s.io/cluster-name标签，应将其作为查询的第一级过滤条件。 - 避免跨资源 JOIN：由于资源之间通过
ownerReferences关联，查询时应尽量使用fieldSelector而非在应用层做内存 JOIN。 - 关注
status而非spec：对于监控与告警场景，status字段变化频率远高于spec，应优先对status字段建立索引或缓存。
以下 SVG 图展示了基于设计哲学的查询优化决策流程：
2.6 小结：从资源模型到查询策略
Cluster API 的资源模型并非随意设计，而是围绕声明式、分层与可组合三大哲学构建。理解这一哲学，才能在设计查询优化与样本留存策略时做出正确取舍：
- Cluster 是查询的“入口点”，应优先过滤。
- MachineDeployment / MachineSet 是“聚合视图”，适合批量状态查询。
- Machine 是“原子单元”，适合细粒度故障排查与样本留存。
- 标签与 ownerReferences 是查询的“索引命脉”，必须合理利用。
下一阶段准备：在掌握资源模型与设计哲学后，第 3 章将深入分析 Cluster API 的 etcd 存储模式与常见查询瓶颈，为后续的索引优化与缓存策略奠定基础。