2. Resource Model 核心原理：资源定义、资源状态机、资源控制器模式
Resource Model（资源模型）是 Kubernetes 及其衍生平台实现声明式运维的基石。在租户隔离升级场景中，理解 Resource Model 的三个核心要素——资源定义、资源状态机、资源控制器模式——是定位故障根因的前提。本节从这三个维度展开，并聚焦于升级过程中资源状态迁移与控制器协调的典型异常模式。
2.1 资源定义：从 Spec 到 Status 的契约
每个资源对象由 Spec（期望状态）和 Status（实际状态）两部分组成。租户隔离升级中，资源定义必须包含租户标识与版本约束。
| 字段 | 说明 | 升级场景关键点 |
|---|---|---|
| apiVersion | 资源版本号，如 v1、v2beta1 |
升级时需校验版本兼容性，避免 CRD 版本不匹配 |
| metadata.namespace | 命名空间，用于租户隔离 | 升级过程中 namespace 可能被冻结或迁移 |
| spec.tenantID | 租户标识（自定义字段） | 控制器据此判断资源归属，升级时需保持一致性 |
| spec.version | 资源期望版本号 | 升级控制器通过比对 spec.version 触发迁移 |
| status.observedVersion | 控制器观测到的实际版本 | 若 observedVersion 与 spec.version 不一致，说明升级未完成 |
| status.conditions | 状态条件列表，如 Ready、Upgrading、Failed | 升级故障排查时，conditions 是首要检查项 |
故障排查要点： 升级过程中若
status.observedVersion 长期未更新至 spec.version，应优先检查控制器日志与 RBAC 权限，而非直接操作资源对象。
2.2 资源状态机：升级过程中的状态迁移
资源状态机定义了资源从创建到终态的合法路径。在租户隔离升级场景中，状态机需要额外引入 Upgrading 和 Rollback 状态。下图展示了核心状态迁移关系：
升级故障排查提示： 当资源卡在 Upgrading 状态超过预期时间，应检查：
1) 升级控制器是否仍在运行；
2) 租户隔离策略是否阻止了状态写入；
3) 目标版本对应的 CRD 是否已注册。
1) 升级控制器是否仍在运行；
2) 租户隔离策略是否阻止了状态写入；
3) 目标版本对应的 CRD 是否已注册。
2.3 资源控制器模式：调谐循环与故障自愈
资源控制器通过 调谐循环（Reconcile Loop） 持续将实际状态拉向期望状态。在租户隔离升级中，控制器需要感知租户边界，避免跨租户干扰。下图展示了控制器的内部架构与升级场景下的工作流程：
常见故障模式： 升级控制器因租户隔离策略（如 namespace 级别的 RBAC 限制）导致 Status 更新失败，调谐循环陷入“读取 Spec → 校验租户 → 执行升级 → 更新 Status 失败 → 重试”的死循环。此时应检查控制器 ServiceAccount 是否具备目标 namespace 的 patch 权限。
2.4 三者关系与升级故障排查映射
资源定义、状态机、控制器模式三者构成闭环：
- 资源定义 提供升级的输入（Spec）与输出（Status）；
- 状态机 定义升级过程的合法路径与终态；
- 控制器模式 驱动状态机流转，并处理异常。
在租户隔离升级故障排查中，应遵循以下检查顺序：
- 查定义：确认资源 Spec 中 tenantID 与 version 字段正确，Status 中 conditions 是否包含错误信息；
- 查状态：确认资源当前状态是否在状态机定义的合法路径上，是否卡在 Upgrading 或 Failed；
- 查控制器：检查控制器日志中是否存在调谐错误，确认 Informer 是否正常监听资源变化，WorkQueue 是否堆积。
核心原则： 升级故障的根因通常不在资源本身，而在控制器无法正确完成“读取 Spec → 校验 → 执行 → 更新 Status”的闭环。Resource Model 的三个要素为故障排查提供了结构化的分析框架。