2. Kubernetes Federation 基础：Federation 架构（KubeFed）、控制平面与成员集群、API 类型（ClusterPropagatedVersion）
在开始治理版本漂移之前，必须理解 Kubernetes Federation（联合集群）的核心机制。KubeFed（Kubernetes Cluster Federation）是 CNCF 孵化的官方项目，它允许用户将多个独立的 Kubernetes 集群统一管理，实现跨集群的资源分发、服务发现和策略治理。本章将深入剖析 KubeFed 的架构、控制平面与成员集群的交互关系，以及关键的 API 类型——ClusterPropagatedVersion。
2.1 KubeFed 架构总览
KubeFed 采用“中心-辐射”模型，由一个 Host Cluster（宿主集群） 作为控制平面，管理多个 Member Cluster（成员集群）。宿主集群运行 KubeFed 控制面组件，成员集群仅需安装 KubeFed 代理（Agent）或通过 API 接入。这种设计将跨集群的编排逻辑集中在控制平面，降低了成员集群的复杂度。
关键概念： KubeFed 不直接调度 Pod，而是通过 Federated API 将资源模板（Template）分发到成员集群，由成员集群自身的调度器完成实际部署。这种“推模式”确保了成员集群的自治性。
2.2 控制平面与成员集群
KubeFed 控制平面运行在宿主集群上，由多个控制器和 API 扩展组成。成员集群通过注册（Cluster API）加入联邦，控制平面负责维护集群列表和健康状态。
| 组件 | 所在位置 | 核心职责 |
|---|---|---|
| Federation API Server | 宿主集群 | 提供 Federated API（如 FederatedDeployment），存储资源模板和分发策略 |
| Federation Controller | 宿主集群 | 监听 Federated API 变化，协调资源分发到成员集群 |
| Sync Controller | 宿主集群 | 将资源模板同步到目标成员集群，处理差异和冲突 |
| Scheduler | 宿主集群 | 根据策略（如地理分布、资源配额）决定资源分发到哪些成员集群 |
| KubeFed Agent | 成员集群 | 接收控制平面指令，在本地创建/更新/删除资源，并上报状态 |
实践要点： 成员集群不需要安装完整的 KubeFed 控制面，只需部署轻量级 Agent 或通过 ServiceAccount 接入。这降低了成员集群的运维负担，也便于将已有集群快速纳入联邦管理。
2.3 API 类型：ClusterPropagatedVersion
ClusterPropagatedVersion（CPV） 是 KubeFed 中用于追踪资源版本的核心 API 对象。它记录了某个 Federated 资源在 每个成员集群 上的实际版本状态，是检测版本漂移的关键数据源。
CPV 的工作原理如下：
- 自动生成： 当用户创建 FederatedDeployment 等资源时，KubeFed 自动为每个成员集群生成对应的 CPV 对象。
- 版本追踪： CPV 包含
templateVersion（模板版本）和overrideVersion（覆盖版本）两个字段，分别记录资源模板和覆盖策略的变更次数。 - 状态上报： 成员集群的 Agent 定期将本地资源版本与 CPV 对比，若不一致则标记为“漂移”。
# ClusterPropagatedVersion 示例（YAML）
apiVersion: types.kubefed.io/v1beta1
kind: ClusterPropagatedVersion
metadata:
name: nginx-deployment
namespace: default
spec:
# 关联的 Federated 资源
template: nginx-deployment
# 目标成员集群列表
clusters:
- name: cluster-beijing
- name: cluster-shanghai
status:
# 每个集群的版本状态
clusterVersions:
- clusterName: cluster-beijing
version: "12345"
templateVersion: "3"
overrideVersion: "1"
observedGeneration: 2
- clusterName: cluster-shanghai
version: "12340"
templateVersion: "2"
overrideVersion: "1"
observedGeneration: 2
# 全局版本
templateVersion: "3"
overrideVersion: "1"
版本漂移检测： 当成员集群的
templateVersion 或 overrideVersion 与控制平面不一致时，说明该集群的资源版本已漂移。Kyverno 可以通过准入 Webhook 监听 CPV 状态，自动触发修复策略。
2.4 关键 API 类型对比
KubeFed 定义了多种 API 类型来支持资源分发和版本管理。下表对比了最常用的几种：
| API 类型 | 作用域 | 核心字段 | 用途 |
|---|---|---|---|
| FederatedDeployment | 命名空间 | template, placement, overrides | 定义跨集群的 Deployment 模板和分发策略 |
| ClusterPropagatedVersion | 命名空间 | templateVersion, overrideVersion, clusterVersions | 追踪每个成员集群的资源版本状态 |
| FederatedCluster | 集群 | apiEndpoint, secretRef, conditions | 注册和管理成员集群的连接信息 |
| FederatedTypeConfig | 集群 | targetType, namespaced, statusType | 配置哪些 Kubernetes 资源类型可以被联邦管理 |
版本漂移治理切入点： ClusterPropagatedVersion 是 Kyverno 策略的最佳监听对象。通过 Kyverno 的
generate 或 mutate 规则，可以在检测到 CPV 版本不一致时，自动触发资源重新同步或告警，实现版本漂移的闭环治理。