4. Cluster Inventory 定义：什么是集群清单、Inventory 的核心字段与元数据模型
在多集群架构中，Cluster Inventory（集群清单） 是对所有纳管集群的标准化元数据描述集合。它不仅仅是集群名称与地址的简单列表，而是包含集群身份、网络拓扑、资源容量、版本信息、标签属性以及健康状态的结构化数据模型。Inventory 是版本差异校验、资源调度、故障隔离和租户边界划分的数据基础。
4.1 什么是集群清单
集群清单（Cluster Inventory）是一个集中维护的、实时或准实时更新的集群元数据注册表。它解决了以下核心问题：
- 发现与注册：自动或手动将新集群纳入管理范围，生成唯一标识。
- 状态感知：记录集群的在线/离线、健康/异常状态。
- 版本追踪：记录 Kubernetes 版本、节点操作系统版本、核心组件版本。
- 资源画像：描述集群的总资源容量（CPU、内存、GPU）与当前水位。
- 租户归属：标记集群所属的租户、环境（生产/预发/测试）、地域。
实践要点：Inventory 数据通常存储在控制面（如全局管理集群）的 etcd 或外部 CMDB 中，通过 Agent 或 API 定期上报心跳与元数据变更。
4.2 Inventory 核心字段
一个完整的 Cluster Inventory 记录通常包含以下核心字段组。下表展示了标准化的字段定义与示例：
| 字段组 | 字段名 | 类型 | 说明 | 示例值 |
|---|---|---|---|---|
| 身份标识 | cluster_id |
UUID | 全局唯一集群标识 | c-9a3b7e2f-1d4c |
cluster_name |
string | 集群可读名称 | prod-shanghai-01 |
|
cluster_type |
enum | 集群类型（ACK/TKE/自建） | ACK |
|
| 网络拓扑 | api_server_endpoint |
string | API Server 访问地址 | https://10.0.1.100:6443 |
pod_cidr |
string | Pod 网络 CIDR | 172.16.0.0/16 |
|
| 版本信息 | k8s_version |
string | Kubernetes 版本 | v1.28.3 |
node_os_version |
string | 节点操作系统版本 | Ubuntu 22.04 LTS |
|
kubelet_version |
string | kubelet 版本 | v1.28.3 |
|
| 资源容量 | total_cpu_cores |
int | 总 CPU 核数 | 128 |
total_memory_gb |
int | 总内存（GB） | 512 |
|
| 租户归属 | tenant_id |
string | 所属租户 ID | t-tenant-finance |
environment |
enum | 环境标签 | production |
|
| 健康状态 | health_status |
enum | 集群健康度 | healthy |
4.3 元数据模型设计
Inventory 的元数据模型采用分层设计，兼顾扩展性与查询效率。模型分为三层：
- 基础层（Base Layer）：包含集群 ID、名称、类型、API Server 地址等不可变或低频变更字段。
- 动态层（Dynamic Layer）：包含版本信息、资源容量、节点数量、健康状态等高频变更字段，由 Agent 定期上报更新。
- 标签层（Label Layer）：以 Key-Value 形式存储自定义标签，用于租户、环境、地域、项目等业务维度的灵活标记。
模型优势：分层设计使得基础数据与动态数据分离，减少 etcd 写入压力；标签层支持按租户、环境等维度快速过滤集群，是版本差异校验中“按租户边界筛选集群”的关键支撑。
4.4 Inventory 元数据模型结构图
下图展示了 Cluster Inventory 的元数据模型分层结构及各层核心字段：
4.5 Inventory 在版本差异校验中的角色
Cluster Inventory 是版本差异校验流程的起点与数据源。其核心作用体现在以下流程中：
- 集群筛选：根据租户 ID、环境标签从 Inventory 中过滤出目标集群列表。
- 版本快照：从 Inventory 的动态层读取每个集群的
k8s_version、kubelet_version等版本字段。 - 差异比对：将目标集群的版本信息与基准版本（如全局期望版本）进行比对，生成差异列表。
- 结果回写：将校验结果（合规/不合规、版本偏差值）写回 Inventory 的标签层或扩展字段，供后续审计与可视化使用。
常见陷阱：Inventory 中的版本信息若未及时更新（如 Agent 上报周期过长），会导致差异校验结果滞后。建议将版本字段的上报间隔控制在 5 分钟以内，并配合主动探测机制兜底。
4.6 Inventory 数据一致性保障
为确保版本差异校验的准确性，Inventory 数据必须满足以下一致性要求：
- 强一致性：集群注册与注销操作需通过分布式锁或事务保证，避免出现幽灵集群。
- 最终一致性：动态层字段允许短暂延迟，但需通过版本号（
resource_version）机制避免覆盖旧数据。 - 心跳超时：若集群超过 N 个周期未上报心跳，Inventory 自动将其标记为
unknown状态，差异校验时跳过该集群。