1. Federation 架构总览：KubeFed 控制平面与资源模型协同
KubeFed（Kubernetes Federation）通过一个独立的控制平面，将多个成员集群抽象为一个统一的资源池。其核心设计围绕控制平面组件与资源模型的协同展开。理解这种协同关系，是定位调度失败、传播中断、版本冲突等故障的前提。
1.1 控制平面三大组件
KubeFed 控制平面由三个核心组件构成，它们共同维护联邦资源的生命周期：
| 组件 | 职责 | 故障排查关注点 |
|---|---|---|
| API Server | 提供联邦 API（FederatedTypeConfig、ClusterPropagatedVersion 等 CRD），存储联邦资源状态。 | API 响应延迟、CRD 注册失败、etcd 存储异常。 |
| Controller Manager | 运行同步控制器，监听联邦资源变化，驱动成员集群状态收敛。 | 控制器循环阻塞、Leader 选举失败、Reconcile 逻辑死锁。 |
| Scheduler | 根据调度策略（如集群标签、资源余量）决定资源应分发到哪些成员集群。 | 调度策略不匹配、集群不可用导致调度失败、调度器缓存过期。 |
排查提示： 当联邦资源无法下发时，优先检查 Controller Manager 的日志中是否出现 "Reconcile error" 或 "Failed to update status" 关键字；若调度结果不符合预期，则需审查 Scheduler 的调度策略配置及集群健康状态。
1.2 资源模型核心对象
KubeFed 的资源模型建立在两个关键 CRD 之上，它们构成了控制平面与成员集群之间的数据桥梁：
- FederatedTypeConfig (FTC)：定义哪种 Kubernetes 资源类型（如 Deployment、Service）需要被联邦管理，以及该类型在成员集群中的传播行为（如是否启用状态收集、是否使用命名空间映射）。
- ClusterPropagatedVersion (CPV)：记录每个成员集群中联邦资源的最新版本号，用于检测成员集群中的资源是否与控制平面期望的状态一致。
1.3 协同关系：从 FTC 到 CPV 的闭环
控制平面组件与资源模型的协同遵循一个清晰的闭环流程：
- 注册与发现： 用户创建 FederatedTypeConfig 对象，告知 KubeFed 需要管理 "Deployment" 类型。Controller Manager 中的 FTC 控制器 检测到新 FTC，自动在 API Server 中注册对应的联邦类型模板（如 FederatedDeployment）。
- 资源创建与调度： 用户创建 FederatedDeployment 实例。Scheduler 根据 FTC 中定义的调度策略，计算目标集群列表，并将调度结果写入 FederatedDeployment 的 Status 字段。
- 传播与同步： Controller Manager 中的 同步控制器 监听到 FederatedDeployment 状态更新，读取目标集群列表，将资源模板（Deployment YAML）推送到每个目标成员集群的 API Server。
- 版本追踪： 每次成功推送后，同步控制器在控制平面中创建或更新对应的 ClusterPropagatedVersion 对象，记录该资源在特定集群中的版本哈希。当成员集群中的资源被外部修改时，版本哈希会与控制平面记录的 CPV 不一致，触发重新同步。
协同故障典型场景： 若 FTC 配置错误（如未启用状态收集），同步控制器将无法创建 CPV，导致控制平面无法感知成员集群中的资源状态变化，进而引发"资源已下发但状态始终为 Pending"的故障。
1.4 协同架构总览图
下图展示了 KubeFed 控制平面组件与资源模型之间的数据流与依赖关系：
1.5 协同故障排查矩阵
基于上述协同关系，以下矩阵总结了常见故障模式及其根因定位路径：
| 故障现象 | 可能根因 | 排查入口 |
|---|---|---|
| FederatedDeployment 创建后无调度结果 | Scheduler 未启动或调度策略未匹配任何集群 | 检查 Scheduler 日志、FTC 中的 schedulerName 字段 |
| 资源已调度但成员集群未收到 | 同步控制器异常或 FTC 中 propagationEnabled 为 false | 查看 Controller Manager 日志、FTC 配置 |
| 成员集群资源被修改后控制平面未恢复 | CPV 版本哈希未更新或状态收集未启用 | 检查 CPV 对象中的 versionHash、FTC 中的 statusCollection 字段 |
| API Server 返回 CRD 未找到错误 | FTC 引用的资源类型未在控制平面注册 | 确认 API Server 中已安装对应 CRD、检查 FTC 的 template 字段 |
关键原则： 在排查协同故障时，始终遵循"FTC 配置 → 调度结果 → CPV 版本 → 成员集群状态"的链路顺序。跳过 FTC 直接检查成员集群，往往会遗漏配置层面的根因。