1. Federation 架构总览：KubeFed 控制平面、成员集群、联邦资源类型、调度与权限的核心挑战

Kubernetes Federation（KubeFed）通过一个统一的控制平面，将多个物理或逻辑上独立的 Kubernetes 集群抽象为一个逻辑集群。本章从架构组件、资源模型、调度机制和权限边界四个维度，建立 Federation 调试的全局认知。

1.1 KubeFed 控制平面架构

KubeFed 控制平面通常部署在某个“宿主集群”或独立的“联邦集群”中，由以下核心组件构成：

• Federation API Server：提供联邦资源（FederatedResource）的 CRD 注册与 API 代理。
• Federation Controller Manager：包含同步控制器、调度控制器、状态收集器等核心循环。
• DNS / Ingress Controller：跨集群服务发现与流量分发。
• Member Cluster 注册表：维护成员集群的 kubeconfig 与健康状态。

1.2 联邦资源类型与三级模型

KubeFed 将原生 Kubernetes 资源（Deployment、Service、ConfigMap 等）包装为联邦资源。每个联邦资源由三个核心对象组成：

1.3 跨集群调度核心机制

KubeFed 的调度并非实时调度 Pod，而是通过 ReplicaSchedulingPreference (RSP) 控制副本分布。调度决策基于以下输入：

• 集群权重：每个集群分配一个权重值，副本按权重比例分配。
• 最小副本数：每个集群至少保留的副本数，用于保证基础容量。
• 最大副本数：防止单个集群负载过高。
• 重新平衡策略：当集群加入/离开或权重变化时，是否自动迁移副本。

# ReplicaSchedulingPreference 示例
apiVersion: scheduling.kubefed.io/v1alpha1
kind: ReplicaSchedulingPreference
metadata:
  name: my-app-rsp
  namespace: default
spec:
  targetTemplate:
    # 关联的联邦资源
    apiVersion: types.kubefed.io/v1beta1
    kind: FederatedDeployment
    name: my-app
  overrides:
    # 集群级别覆盖
    - clusterName: us-east-1
      minReplicas: 3
      maxReplicas: 10
      weight: 60
    - clusterName: eu-west-1
      minReplicas: 2
      maxReplicas: 8
      weight: 40
  totalReplicas: 10
  rebalance: true

1.4 租户权限边界的核心挑战

Federation 环境下的权限管理比单集群复杂一个数量级，主要挑战集中在以下四个维度：

1.5 调度与权限的交叉调试场景

在实际运维中，调度失败和权限问题经常交织出现。以下是最常见的三种交叉场景：

1. 副本无法调度到目标集群：检查 RSP 权重配置 → 检查目标集群的 ResourceQuota 是否充足 → 检查 ServiceAccount 在目标集群的 RBAC 权限。
2. 覆盖策略未生效：验证覆盖策略中的 clusterName 是否与成员集群注册表中的名称完全一致 → 检查目标集群的 ValidatingWebhookConfiguration 是否拦截了覆盖字段。
3. 联邦资源同步失败：查看 Federation Controller Manager 日志中的 sync 错误 → 确认成员集群的 kubeconfig 未过期 → 检查目标集群的 ClusterRole 是否包含对应资源的 create/update 权限。