Kubernetes 亲和性与反亲和性配置记录

最近看一个服务的调度配置，发现它同时用了 nodeSelector、nodeAffinity 和 podAntiAffinity。表面上看是“让服务跑到指定节点池，并尽量分散”，但真正排查 Pending 的时候，发现这些规则叠在一起以后不太直观。

这篇简单记录一下我自己看调度规则时的判断顺序。

我一开始看错的地方是：以为 preferred 写了就一定会分散，后来才意识到它只是调度器打分时的偏好。只要资源、污点、PVC 或其他硬条件把节点集合压小，软亲和性很容易被牺牲。

先看节点标签

亲和性本质上还是围绕 label 做匹配。排查前先看节点上到底有没有这些 label：

1
2
3
4
5
6
kubectl get nodes --show-labels

kubectl get nodes \
  -L kubernetes.io/os \
  -L node-role.kubernetes.io/worker \
  -L topology.kubernetes.io/zone

如果 YAML 里写了 topology.kubernetes.io/zone，但节点上根本没有这个 label，后面分析半天都是偏的。

nodeSelector 和 nodeAffinity

nodeSelector 比较直接，只能做简单的等值匹配：

1
2
3
spec:
  nodeSelector:
    node-role.kubernetes.io/worker: "true"

nodeAffinity 更灵活，可以写 In、NotIn、Exists、DoesNotExist、Gt、Lt 这些操作符，也可以区分硬约束和软约束。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-server
spec:
  replicas: 3
  selector:
    matchLabels:
      app: api-server
  template:
    metadata:
      labels:
        app: api-server
    spec:
      affinity:
        nodeAffinity:
          requiredDuringSchedulingIgnoredDuringExecution:
            nodeSelectorTerms:
              - matchExpressions:
                  - key: node-role.kubernetes.io/worker
                    operator: Exists
                  - key: kubernetes.io/os
                    operator: In
                    values:
                      - linux
          preferredDuringSchedulingIgnoredDuringExecution:
            - weight: 80
              preference:
                matchExpressions:
                  - key: topology.kubernetes.io/zone
                    operator: In
                    values:
                      - cn-east-1a
      containers:
        - name: api-server
          image: nginx:1.27

requiredDuringSchedulingIgnoredDuringExecution 是硬条件，不满足就不会调度。preferredDuringSchedulingIgnoredDuringExecution 是软条件，调度器会尽量满足，但不满足也可以调度。

IgnoredDuringExecution 的意思是：Pod 已经调度成功后，如果节点 label 后面变了，Kubernetes 不会因为这个亲和性规则把 Pod 赶走。

还有一个容易忽略的点：如果同时写了 nodeSelector 和 nodeAffinity，它们都必须满足。不是二选一。

多个 nodeSelectorTerms 之间是 OR，只要满足其中一个 term 就可以。同一个 term 里的多个 matchExpressions 是 AND，必须全部满足。

我通常会把它翻译成一行布尔表达式再看：

1
2
3
4
5
6
7
8
9
nodeSelector
AND
(term1.expressionA AND term1.expressionB OR term2.expressionC)
AND
pod anti-affinity hard rules
AND
taints/tolerations
AND
resources

这么写出来以后，很多 Pending 就不神秘了。不是 Kubernetes 调度器“抽风”，而是自己把可用节点交集写没了。

podAffinity 和 podAntiAffinity

podAffinity 不是看节点 label，而是看“某个拓扑域里有没有符合 label 的 Pod”。

比如希望业务 Pod 尽量跟缓存 Pod 在同一个可用区，减少跨可用区访问：

1
2
3
4
5
6
7
affinity:
  podAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
      - labelSelector:
          matchLabels:
            app: redis
        topologyKey: topology.kubernetes.io/zone

这个规则要小心。如果 redis 本身还没起来，或者 redis 不在当前 namespace，新的业务 Pod 就可能 Pending。podAffinity 默认只匹配当前 namespace，如果要跨 namespace，需要显式写 namespaces 或 namespaceSelector。

更常见的是 podAntiAffinity，比如同一个 Deployment 的多个副本尽量不要落在同一个节点：

1
2
3
4
5
6
7
8
9
affinity:
  podAntiAffinity:
    preferredDuringSchedulingIgnoredDuringExecution:
      - weight: 100
        podAffinityTerm:
          labelSelector:
            matchLabels:
              app: api-server
          topologyKey: kubernetes.io/hostname

这里用的是 preferred，所以只是尽量分散。如果节点资源紧张，多个 Pod 仍然可能被放到同一个节点。

这个配置看起来短，但里面有几个字段不能只按字面理解。

weight: 100 只在 preferredDuringSchedulingIgnoredDuringExecution 里出现，范围是 1 到 100。它不是“强制程度”，而是调度器打分时这个偏好的权重。多个 preferred 规则同时存在时，调度器会把满足偏好的节点加分，最后选择综合分数更高的节点。也就是说，weight: 100 仍然是软偏好，不会让 Pod Pending。

podAffinityTerm 才是真正描述“跟谁保持距离”的规则。它至少要看三个东西：

labelSelector：选择已有 Pod。
topologyKey：定义“同一个拓扑域”。
namespaces / namespaceSelector：决定跨不跨 namespace 查已有 Pod。

topologyKey: kubernetes.io/hostname 的意思不是“按节点名匹配 Pod label”，而是看节点上这个 label 的值。通常每个节点的 kubernetes.io/hostname 不同，所以效果就是“尽量不要放到同一个节点”。如果换成 topology.kubernetes.io/zone，含义就变成“尽量不要放到同一个可用区”。

这个差别很大：

1
2
3
kubernetes.io/hostname        节点级分散
topology.kubernetes.io/zone   可用区级分散
topology.kubernetes.io/region 地域级分散，通常不这么用

如果只是想让副本分散到不同节点，用 hostname 就够了。如果想跨可用区做容灾，要用 zone，但这时候更推荐一起评估 topologySpreadConstraints，因为它表达“分布倾斜度”会更直观。

如果要强制分散，可以写成 required：

1
2
3
4
5
6
7
affinity:
  podAntiAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
      - labelSelector:
          matchLabels:
            app: api-server
        topologyKey: kubernetes.io/hostname

如果集群只有 2 个可用节点，但 Deployment 要 3 个副本，第 3 个 Pod 很可能 Pending。

大集群里还要注意性能。官方文档提醒 inter-pod affinity/anti-affinity 在大规模集群中可能拖慢调度，因为调度器需要跨节点检查已有 Pod 的标签和拓扑域。简单说，节点和 Pod 越多，这类规则越不便宜。能用 topologySpreadConstraints 表达“均匀分布”的场景，我会优先考虑它。

还有一个准入层面的细节：对于 requiredDuringSchedulingIgnoredDuringExecution 的 Pod anti-affinity，Kubernetes 默认的 LimitPodHardAntiAffinityTopology 准入控制器会把 topologyKey 限制为 kubernetes.io/hostname。也就是说，hard anti-affinity 想直接用 zone 做强约束，可能会被准入策略拦住。这个限制是为了避免过重、过宽的硬反亲和规则影响调度。

podAntiAffinity 里容易漏掉的配置

上面的例子只用了 matchLabels，实际项目里经常不够。

matchExpressions：不要只会 matchLabels

如果同一个服务有多个组件，不想跟某几类组件混在一起，可以用 matchExpressions：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
affinity:
  podAntiAffinity:
    preferredDuringSchedulingIgnoredDuringExecution:
      - weight: 80
        podAffinityTerm:
          labelSelector:
            matchExpressions:
              - key: app
                operator: In
                values:
                  - api-server
              - key: component
                operator: NotIn
                values:
                  - canary
          topologyKey: kubernetes.io/hostname

这个规则的意思是：调度当前 Pod 时，尽量避开已经运行了 app=api-server 且 component 不是 canary 的节点。

matchLabels 和 matchExpressions 是 AND 关系，不是 OR。这个点很容易写错。如果你既写了：

1
2
3
4
5
6
7
matchLabels:
  app: api-server
matchExpressions:
  - key: component
    operator: In
    values:
      - stable

那它匹配的是 app=api-server AND component in (stable)。

namespaces / namespaceSelector：默认只看当前 namespace

podAffinityTerm 默认只匹配当前 Pod 所在 namespace 里的 Pod。这个默认行为有时候会让人误判。

比如你有两个 namespace：

1
2
prod-a/api-server
prod-b/api-server

如果你希望两个 namespace 的 api-server 也不要落到同一个节点，必须显式指定 namespace：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
affinity:
  podAntiAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
      - labelSelector:
          matchLabels:
            app: api-server
        namespaces:
          - prod-a
          - prod-b
        topologyKey: kubernetes.io/hostname

如果 namespace 很多，用 namespaceSelector 更合适。比如只匹配带有 tenant=prod 标签的 namespace：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
affinity:
  podAntiAffinity:
    preferredDuringSchedulingIgnoredDuringExecution:
      - weight: 100
        podAffinityTerm:
          labelSelector:
            matchLabels:
              app: api-server
          namespaceSelector:
            matchLabels:
              tenant: prod
          topologyKey: kubernetes.io/hostname

这里要先给 namespace 打标签：

1
2
kubectl label namespace prod-a tenant=prod
kubectl label namespace prod-b tenant=prod

如果 namespaces 和 namespaceSelector 同时写，匹配范围是两者的并集。都不写时，就是当前 Pod 的 namespace。

matchLabelKeys：跟当前 Pod 的标签值绑定

Kubernetes 还支持 matchLabelKeys。它会从“当前正在调度的 Pod”上取指定 key 的 value，再和 labelSelector 合并。

这个字段适合 Deployment 滚动发布时使用，避免新旧 ReplicaSet 的 Pod 互相干扰。比如不同 revision 的 Pod 都有 pod-template-hash：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
affinity:
  podAntiAffinity:
    preferredDuringSchedulingIgnoredDuringExecution:
      - weight: 100
        podAffinityTerm:
          labelSelector:
            matchLabels:
              app: api-server
          matchLabelKeys:
            - pod-template-hash
          topologyKey: kubernetes.io/hostname

含义是：不仅要匹配 app=api-server，还要拿当前 Pod 的 pod-template-hash 值去匹配已有 Pod。这样调度器更关注同一个 rollout revision 的 Pod 分布，而不是把历史 revision 也算进去。

这个配置比简单的 app=api-server 更细，尤其适合滚动发布时避免新旧版本互相影响调度判断。

mismatchLabelKeys：租户隔离时更有用

mismatchLabelKeys 是另一个容易忽略的字段。它会从当前 Pod 标签里取 key 的值，然后匹配“这个 key 的值不相同”的已有 Pod。

一个典型场景是多租户隔离：不要把不同 tenant 的 Pod 放到同一个节点池或同一个节点。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
affinity:
  podAntiAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
      - mismatchLabelKeys:
          - tenant
        labelSelector:
          matchExpressions:
            - key: tenant
              operator: Exists
        topologyKey: kubernetes.io/hostname

假设当前 Pod 是 tenant=team-a，这个规则会让它排斥同一 hostname 上已有的 tenant!=team-a 的 Pod。

这个字段不要随便用在经常变的 label 上。官方文档也提醒，不要对调度后还可能直接修改的 label 使用这类动态匹配字段，否则 kubelet 不会因为 label 后续变化而重新触发调度。

一个更完整的 Deployment 例子

如果我要给一个生产 API 写“尽量分散，但不要因为节点不足卡死”的配置，会更像这样：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-server
  namespace: prod-a
spec:
  replicas: 4
  selector:
    matchLabels:
      app: api-server
  template:
    metadata:
      labels:
        app: api-server
        tenant: team-a
    spec:
      affinity:
        podAntiAffinity:
          preferredDuringSchedulingIgnoredDuringExecution:
            - weight: 100
              podAffinityTerm:
                labelSelector:
                  matchLabels:
                    app: api-server
                namespaceSelector:
                  matchLabels:
                    tenant: prod
                topologyKey: kubernetes.io/hostname
            - weight: 50
              podAffinityTerm:
                labelSelector:
                  matchLabels:
                    app: api-server
                topologyKey: topology.kubernetes.io/zone
      containers:
        - name: api-server
          image: nginx:1.27

这个配置表达的是：

优先不要和其他 api-server 放在同一节点。
跨 tenant=prod 的 namespace 一起考虑。
次一级偏好是不要都堆在同一个 zone。
因为都是 preferred，所以资源紧张时不会导致 Pod Pending。

如果业务真的要求“一台节点只能跑一个副本”，再把第一条改成 required。但我一般不会一上来就这么做，除非副本数、节点数、扩容策略都已经算清楚。

排查时先看 Events

如果调度失败，不要先猜，直接 describe：

`1`	`kubectl describe pod api-server-xxx -n default`

重点看最后的 Events，常见会看到类似：

1
2
3
Warning  FailedScheduling  default-scheduler  0/3 nodes are available:
1 node(s) didn't match Pod's node affinity/selector,
2 node(s) didn't match pod anti-affinity rules.

然后再反查：

1
2
3
4
kubectl get pod -n default -l app=api-server -o wide
kubectl get nodes \
  -L topology.kubernetes.io/zone \
  -L kubernetes.io/hostname

亲和性配置本身不复杂，复杂的是这些规则会跟资源、污点、PVC、拓扑分布一起叠加。我的习惯是先确认硬约束，再看软约束，不要一上来就改 replicas 或重启。

最后还有一个现实建议：不要为了“看起来高可用”把所有规则都写成 required。亲和性配置的目的应该是表达业务边界，不是把调度器绑死。比如核心服务跨节点分散可以硬一点，普通后台任务用 preferred 往往更合适。