📚 课程目录第4章 Pod调度与拓扑分布约束

4. Pod 调度与拓扑分布约束：topologySpreadConstraints 原理与配置

在 Kubernetes 集群中，默认的调度器（kube-scheduler）仅保证 Pod 被调度到满足资源请求的节点上，但无法保证 Pod 在故障域（如节点、可用区）之间的均匀分布。当 Deployment 的副本数较多时，可能出现多个 Pod 被调度到同一节点或同一可用区的情况，导致单点故障风险升高。

拓扑分布约束（Topology Spread Constraints） 是 Kubernetes 1.19+（GA 于 1.24）提供的一种细粒度调度策略，允许用户显式定义 Pod 在集群拓扑域中的分布规则，从而实现故障域隔离与高可用部署。

4.1 核心概念与字段说明

拓扑分布约束通过 spec.topologySpreadConstraints 字段定义在 Pod 模板中。每个约束包含以下关键字段：

字段	类型	说明
`topologyKey`	string	节点标签的键，用于定义拓扑域。例如 `kubernetes.io/hostname`（节点级）、`topology.kubernetes.io/zone`（可用区级）
`maxSkew`	int	允许的最大不均衡度。即任意两个拓扑域之间 Pod 数量的最大差值
`whenUnsatisfiable`	string	当约束无法满足时的行为：`DoNotSchedule`（硬约束，Pod 保持 Pending）或 `ScheduleAnyway`（软约束，优先尝试但允许违反）
`labelSelector`	LabelSelector	用于匹配 Pod 的标签选择器。通常设置为 Deployment 的 `matchLabels`，确保只统计属于同一工作负载的 Pod
`matchLabelKeys`	[]string	（1.27+）从 Pod 标签中提取键，与 `labelSelector` 联合使用，用于滚动更新场景
`nodeAffinityPolicy`	string	（1.27+）控制节点亲和性对拓扑域计算的影响：`Honor`（仅考虑满足节点亲和性的节点）或 `Ignore`（考虑所有节点）

关键理解： maxSkew 控制分布均匀度。例如 maxSkew: 1 表示任意两个拓扑域之间的 Pod 数量差不超过 1，这是最严格的均匀分布。

4.2 工作原理与调度流程

调度器在处理拓扑分布约束时，遵循以下步骤：

识别拓扑域： 根据 topologyKey 获取集群中所有节点的标签值，每个不同的标签值对应一个拓扑域。
统计现有 Pod： 使用 labelSelector 匹配已调度的 Pod，按拓扑域统计每个域中的 Pod 数量。
计算候选节点： 对于每个待调度 Pod，计算将其放置到某个节点后，该节点所在拓扑域的 Pod 数量，并检查是否满足 maxSkew 约束。
选择最优节点： 在满足约束的节点中，优先选择使全局 skew 最小的节点（软约束时优先选择，硬约束时仅选择满足条件的节点）。

4.3 配置示例与场景分析

4.3.1 节点级均匀分布（hostname）

以下配置确保 Deployment 的 Pod 在集群节点之间均匀分布，任意两个节点上的 Pod 数量差不超过 1：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web-app
spec:
  replicas: 6
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      topologySpreadConstraints:
        - maxSkew: 1
          topologyKey: kubernetes.io/hostname
          whenUnsatisfiable: DoNotSchedule
          labelSelector:
            matchLabels:
              app: web
      containers:
        - name: nginx
          image: nginx:1.25

  效果说明： 假设集群有 3 个节点，调度器会尽量在每个节点上放置 2 个 Pod。如果某个节点故障，最多只有 2 个 Pod 受影响，而非全部 6 个。

4.3.2 可用区级故障域隔离（zone）

对于跨可用区部署，使用 topology.kubernetes.io/zone 作为拓扑键：

topologySpreadConstraints:
  - maxSkew: 1
    topologyKey: topology.kubernetes.io/zone
    whenUnsatisfiable: DoNotSchedule
    labelSelector:
      matchLabels:
        app: web

当集群分布在 3 个可用区时，6 个副本的 Deployment 会在每个可用区放置 2 个 Pod。即使整个可用区宕机，服务仍保持 4 个副本正常运行。

4.3.3 多约束组合

可以同时定义多个拓扑分布约束，实现多层级故障域隔离：

topologySpreadConstraints:
  - maxSkew: 1
    topologyKey: topology.kubernetes.io/zone
    whenUnsatisfiable: DoNotSchedule
    labelSelector:
      matchLabels:
        app: web
  - maxSkew: 1
    topologyKey: kubernetes.io/hostname
    whenUnsatisfiable: DoNotSchedule
    labelSelector:
      matchLabels:
        app: web

注意： 多约束组合会增加调度器的计算复杂度，且可能因约束冲突导致 Pod 无法调度。建议先使用 ScheduleAnyway 进行验证，确认集群拓扑满足约束后再切换为 DoNotSchedule。

4.4 常见问题与最佳实践

问题场景	原因	解决方案
Pod 一直 Pending	硬约束无法满足，所有候选节点都会导致 maxSkew 超标	增加节点数量、降低 maxSkew 值、或改用 `ScheduleAnyway`
分布不均匀	节点标签不一致，部分节点缺少 topologyKey 对应的标签	检查节点标签，确保所有节点都有正确的拓扑标签
滚动更新时分布异常	旧 Pod 和新 Pod 标签不同，导致统计不准确	使用 `matchLabelKeys`（1.27+）或确保新旧 Pod 共享公共标签
与节点亲和性冲突	节点亲和性将 Pod 限制到特定节点集，与拓扑分布约束矛盾	使用 `nodeAffinityPolicy: Honor` 明确计算范围

4.5 与 PodAntiAffinity 的对比

拓扑分布约束与 Pod 反亲和性（PodAntiAffinity）都能实现 Pod 分散部署，但适用场景不同：

特性	topologySpreadConstraints	PodAntiAffinity
控制粒度	全局均匀分布，考虑所有拓扑域	局部约束，仅限制与特定 Pod 的关系
均匀度控制	支持 maxSkew 精确控制	仅支持 required/preferred，无定量控制
多域支持	原生支持多约束组合	需为每个域定义独立规则
性能开销	较低，调度器内置优化	较高，需遍历所有 Pod 进行匹配
推荐场景	Deployment 跨故障域均匀分布	避免关键 Pod 共置（如数据库主从）

最佳实践： 对于大多数 Deployment 场景，优先使用 topologySpreadConstraints 实现故障域隔离。仅在需要精确控制特定 Pod 之间的共置关系时，才考虑使用 PodAntiAffinity。

4.6 验证与调试

部署后，使用以下命令验证 Pod 分布情况：

# 查看 Pod 所在节点
kubectl get pods -o wide -l app=web

# 按节点统计 Pod 数量
kubectl get pods -l app=web -o jsonpath='{range .items[*]}{.spec.nodeName}{"\n"}{end}' | sort | uniq -c

# 按可用区统计 Pod 数量
kubectl get nodes -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.metadata.labels.topology\.kubernetes\.io/zone}{"\n"}{end}'

如果 Pod 分布不符合预期，检查调度器日志或使用 kubectl describe pod <pod-name> 查看调度事件中的拓扑约束评估结果。