Kubernetes Topology Spread Constraints vs Pod Affinity and Anti-Affinity
maxSkew, topologyKey, and whenUnsatisfiable decide distribution across zones and nodes. Why required anti-affinity deadlocks at scale and spread degrades instead.

Quick Summary
Pod affinity and topology spread constraints both distribute pods across failure domains, and they differ in what they promise. Pod affinity says "put me near (or away from) pods matching this selector"; topology spread says "keep the counts across domains within this skew", which is a constraint on the distribution rather than on any single pod.
The fields that cause the most confusion: topologyKey is a node label (kubernetes.io/hostname, topology.kubernetes.io/zone), maxSkew is the largest allowed difference between the domain with the most matching pods and the one with the fewest, and whenUnsatisfiable decides whether the constraint blocks scheduling (DoNotSchedule) or merely informs the scores (ScheduleAnyway).
Pod anti-affinity with requiredDuringSchedulingIgnoredDuringExecution on kubernetes.io/hostname is the classic "one replica per node" rule, and it deadlocks at scale: once every node holds one matching pod, the next replica has nowhere to go. Topology spread with maxSkew: 1 and ScheduleAnyway degrades gracefully instead, which is why it replaced anti-affinity for replica spreading in most production manifests.
Basic Syntax & Core Signatures
apiVersion: apps/v1
kind: Deployment
metadata:
name: api
spec:
replicas: 6
selector:
matchLabels: { app: api }
template:
metadata:
labels: { app: api }
spec:
topologySpreadConstraints:
- maxSkew: 1
topologyKey: topology.kubernetes.io/zone
whenUnsatisfiable: DoNotSchedule
labelSelector:
matchLabels: { app: api }
minDomains: 3 # penalty when fewer domains exist
- maxSkew: 1
topologyKey: kubernetes.io/hostname
whenUnsatisfiable: ScheduleAnyway
labelSelector:
matchLabels: { app: api }
affinity:
podAntiAffinity:
preferredDuringSchedulingIgnoredDuringExecution:
- weight: 100
podAffinityTerm:
topologyKey: kubernetes.io/hostname
labelSelector:
matchLabels: { app: api }
containers:
- name: api
image: registry.example.com/shop/api:4.2.0# "Run near the cache": pod affinity with a namespace restriction
affinity:
podAffinity:
requiredDuringSchedulingIgnoredDuringExecution:
- topologyKey: kubernetes.io/hostname
labelSelector:
matchLabels: { app: redis }
namespaces: [cache] # default: the pod's own namespace
namespaceSelector: {} # alternative: any labelled namespacekubectl get nodes -L topology.kubernetes.io/zone,kubernetes.io/hostname
kubectl get pods -l app=api -o custom-columns=\
NAME:.metadata.name,NODE:.spec.nodeName,ZONE:.metadata.labels.topology\\.kubernetes\\.io/zone
kubectl describe pod api-6c7d9f-abcde | grep -A3 "Topology Spread"Key Comparison Table
| Constraint | Guarantees | Fails as |
|---|---|---|
| Pod affinity (required) | Co-located with matching pods | Pending if no domain has a match |
| Pod anti-affinity (required) | Never co-located | Pending when every node has one |
| Pod anti-affinity (preferred) | Best effort | Schedules anyway, unevenly |
Topology spread DoNotSchedule | Skew within maxSkew | Pending, with the skew in the event |
Topology spread ScheduleAnyway | Bias toward balance | Schedules anywhere, warns of skew |
nodeAffinity required | Only matching nodes | Pending with a node-affinity message |
| Topology spread field | Meaning | Default |
|---|---|---|
maxSkew | Allowed difference between the fullest and emptiest domain | required |
topologyKey | Node label defining a domain | required |
whenUnsatisfiable | Hard or soft | required |
labelSelector | Which pods are counted | required |
minDomains | Domains below which the constraint counts as unsatisfiable | 1 |
nodeAffinityPolicy | Whether to honour the pod's node affinity when counting | Honor |
nodeTaintsPolicy | Whether to count tainted nodes as domains | Ignore |
| Symptom | Meaning |
|---|---|
Pending: node(s) didn't match pod anti-affinity rules | Every candidate node already holds a match |
Pending: skew message | A domain is over-full relative to another |
| Pods land in one zone despite spread | topologyKey label missing on nodes |
| Rollout stalls at 1 pending pod | Required anti-affinity with replicas above node count |
Practical Edge Cases & Deep Dives
1. Anti-affinity deadlock and why spread replaced it
nodes: 3, replicas: 4, required anti-affinity on hostname
-> one pod per node, 4th pod Pending foreverA rolling update makes it worse: the Deployment wants to surge a new pod onto a node that already holds a pod matching its own selector (the new pod's labels match too), so the surge pod cannot schedule and maxSurge has to be 0 or the rollout hangs. Topology spread with maxSkew: 1 and ScheduleAnyway allows the imbalance when the cluster genuinely cannot satisfy it, so a scale-up past node count still makes progress — unevenly, which is visible in the metrics rather than in a stuck pod.
2. minDomains and clusters smaller than the intended topology
A three-zone constraint on a two-zone cluster can never satisfy maxSkew: 1 with DoNotSchedule if minDomains: 3 is set — the scheduler treats the missing domain as an empty one and blocks. Without minDomains, the constraint evaluates only over existing domains and happily puts everything in two zones. Set minDomains when zone balance must be enforced and pods going Pending is the correct signal to add capacity.
kubectl describe pod api-6c7d9f-abcde | sed -n '/Topology Spread/,+4p'
# Node: ... -> minDomains: 3, found 2 domains, cannot satisfy maxSkew3. nodeAffinityPolicy and nodeTaintsPolicy change the denominator
Since 1.26 the constraint honours the pod's own node affinity by default (Honor): nodes the pod could not run on anyway are excluded from the skew calculation. nodeTaintsPolicy: Ignore (the default) counts tainted nodes as domains, which over-constrains pods that avoid those nodes. Setting nodeTaintsPolicy: Honor makes the count match where the pod can actually go — the fix when a scale-up is blocked by "skew" on nodes nobody can use.
4. Zone spread with a StatefulSet still needs per-pod topology
Topology spread balances replicas; it does not make a StatefulSet's volumes zone-independent. Each PVC is bound to a zone through its PV, so a pod can only run where its disk lives, and the scheduler's spread constraint is silently secondary to the volume node affinity. Symptom: even distribution in the first deploy, then Pending pods after a scale-up in one zone.
# The scheduler reports which rule won
0/9 nodes are available: 6 node(s) had volume node affinity conflict,
3 node(s) didn't match pod topology spread constraints.The durable pattern is a per-zone StatefulSet or a storage class that provisions in the node's zone with a matching spread constraint and enough zones to tolerate one failing.
5. Pod affinity across namespaces, and the cost of namespaceSelector
podAffinity defaults to the pod's own namespace. Reaching into another one needs either namespaces: [cache] (explicit list) or namespaceSelector. Both make the term depend on objects outside the pod's own tree, so an operator's cache namespace rename silently stops placement. Prefer a stable label on the target namespace and match on kubernetes.io/metadata.name, which is immutable.
Also note that pod affinity has a scheduling cost: the scheduler must index all pods matching the selector on every candidate node. Large clusters with thousands of pods and required pod affinity are measurably slower to schedule than ones using topology spread, which uses precomputed counts per domain.
Common Runtime & Configuration Mistakes
| Symptom | Cause | Fix |
|---|---|---|
Pending after scale-up past node count | Required anti-affinity | Use topology spread, or ScheduleAnyway |
| Rollout hangs at a surge pod | Anti-affinity against own selector | maxSurge: 0, or spread instead |
| Everything in one zone | topologyKey label absent from nodes | Label nodes; verify with -L |
| Skew message despite free capacity | minDomains above existing domains | Lower it, or add a zone |
| Counting tainted nodes as domains | nodeTaintsPolicy: Ignore | Set Honor |
Pods spread but PVC-bound pods Pending | Volume node affinity outweighs spread | Zone-aligned storage per zone |
| Affinity matches nothing after a rename | Cross-namespace selector | Match kubernetes.io/metadata.name |
| Co-location works only sometimes | Preferred affinity is best effort | Required affinity for correctness |
| Scheduler slow with many replicas | Required pod affinity over big selectors | Topology spread |
| Constraint ignored by the scheduler | Old API server, or field typo in the term | Check describe pod output |
Both features are answered by the same question: which domain does this pod count against, and what happens when that domain is full? Choose DoNotSchedule only when a wrong placement is worse than no placement, and prefer spread over anti-affinity for anything whose replica count can grow.
Try matching browser tools
All toolsSmall utilities that fit Kubernetes work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Kubernetes guides
All Kubernetes guideskubectl Output: jsonpath, custom-columns, and the Debugging Commands Worth Knowing
jsonpath for one value in a script, custom-columns for tables people read, and kubectl debug when the container has no shell. Includes the three quoting layers that break jsonpath.
Kubernetes Namespaces, ResourceQuotas, and LimitRanges
A namespace is only a boundary when quota and limit range make it one. Aggregate caps, per-pod defaults, the admission errors they produce, and namespaces stuck Terminating.
Kubernetes StatefulSets: Ordinal Identities, Headless Services, and PVC Lifecycle
Why each StatefulSet pod keeps a name, a DNS record, and its own PVC; how OrderedReady gates startup on readiness; and how partition-based updates canary a single quorum member.
Kubernetes securityContext, Capabilities, and Pod Security Standards
The five fields that remove most container escapes, which of them only exist at container level, and how the restricted profile enforces the same settings at admission.
More in Kubernetes
All Kubernetes guidesThe guides filed next to this one in Kubernetes, in library order.