2. Federation 基础回顾：KubeFed 架构、核心 CRD 与控制平面组件
在深入多集群变更门禁与自动化配置迁移之前，必须牢固掌握 KubeFed 的核心原理。KubeFed（Kubernetes Federation v2）是 CNCF 孵化的开源项目，旨在通过一套统一的控制平面，将多个 Kubernetes 集群抽象为一个逻辑集群。本章将系统梳理其架构分层、关键 CRD 以及控制平面组件的协作关系。
2.1 KubeFed 整体架构分层
KubeFed 采用“宿主集群 + 成员集群”的星型拓扑。宿主集群运行 Federation 控制平面组件，成员集群仅需安装 kubefed 相关资源即可被纳管。架构自上而下分为三层：
- 用户接口层：用户通过
kubefedctl命令行工具或直接 apply Federated CRD 来声明多集群资源。 - 调度与同步层：Federation 控制器负责将 Federated 资源解析为每个成员集群的本地资源，并持续同步状态。
- 成员集群层：实际运行工作负载的 Kubernetes 集群，每个集群内运行由 Federation 同步过来的原生 Deployment、Service 等。
架构要点： KubeFed 不直接管理 Pod，而是通过“模板-覆盖-放置”三要素模型，将多集群资源定义与调度策略解耦。
2.2 核心 CRD 详解
KubeFed 通过一组自定义资源定义（CRD）来抽象多集群资源。以下是最关键的四个 CRD：
| CRD 名称 | 作用域 | 核心字段 | 说明 |
|---|---|---|---|
| FederatedDeployment | 宿主集群 | spec.template, spec.placement, spec.overrides |
定义多集群 Deployment 的模板、放置策略与集群级覆盖 |
| FederatedService | 宿主集群 | spec.template, spec.placement |
多集群 Service 定义，支持跨集群服务发现 |
| ClusterPropagatedVersion | 宿主集群 | status.templateVersion, status.overrideVersion, status.clusterVersions |
记录每个成员集群中已同步资源的版本号，用于变更门禁校验 |
| FederatedCluster | 宿主集群 | spec.secretRef, status.conditions |
注册成员集群的连接信息与健康状态 |
关键理解： ClusterPropagatedVersion 是自动化配置迁移的核心数据源。它记录了每个集群当前生效的模板版本和覆盖版本，门禁系统通过比对“期望版本”与“已传播版本”来判断是否需要触发迁移。
2.3 控制平面组件
KubeFed 控制平面由以下组件构成，它们协作完成资源同步、状态收集与调度决策：
- Federation Controller Manager：核心控制器，运行在宿主集群中。负责监听 Federated 资源的变化，生成对应的原生资源并同步到成员集群。
- Federation API Server：提供 Federated CRD 的 API 注册与存储，通常复用宿主集群的 kube-apiserver。
- Federation Admission Webhook：可选组件，用于在资源创建/更新时执行校验与默认值注入，例如自动添加
federation.k8s.io/placement标签。 - kubefedctl：命令行工具，用于初始化 Federation 控制平面、注册/注销成员集群、启用/禁用 Federated 资源类型。
2.4 资源同步流程示例
以 FederatedDeployment 为例，一次完整的同步流程如下：
- 用户在宿主集群创建
FederatedDeployment对象，包含spec.template（Deployment 模板）、spec.placement（目标集群列表）和可选的spec.overrides（集群级覆盖）。 - Federation Controller Manager 中的同步控制器监听到新对象，根据 placement 确定目标集群。
- 控制器将 template 与 overrides 合并，生成每个集群的最终 Deployment 定义，并通过成员集群的 kube-apiserver 创建/更新。
- 状态控制器收集每个集群中 Deployment 的状态，更新 FederatedDeployment 的
status字段。 - ClusterPropagatedVersion 记录每个集群当前生效的模板版本和覆盖版本，供后续变更门禁比对。
常见陷阱： 如果成员集群的 kube-apiserver 版本与宿主集群差异过大（例如相差两个小版本），可能导致资源同步失败。建议所有成员集群保持 Kubernetes 版本一致，或至少处于同一大版本内。
2.5 本章小结
KubeFed 通过“模板-覆盖-放置”模型将多集群管理抽象为声明式 API。核心 CRD（FederatedDeployment、FederatedService、ClusterPropagatedVersion）构成了自动化配置迁移的数据基础，而 Federation Controller Manager 与 API Server 则提供了同步与状态收集的执行引擎。理解这些基础组件，是后续实现变更门禁与自动化迁移的前提。