Configuring Pod Topology Spread Constraints
1. Understanding Topology Spread
Distribute pods evenly across failure domains (zones, nodes) to maximize availability.
| vs Pod Anti-Affinity | Detail |
|---|
| Granularity | Quantitative skew, not binary |
| Performance | More efficient at scale |
2. Setting Maximum Skew
topologySpreadConstraints:
- maxSkew: 1
topologyKey: topology.kubernetes.io/zone
whenUnsatisfiable: DoNotSchedule
labelSelector: { matchLabels: { app: web } }
| maxSkew | Effect |
|---|
| 1 | Strictest balance (±1 pod) |
| N | Allow up to N pod difference |
3. Configuring When Unsatisfiable
| Value | Behavior |
|---|
| DoNotSchedule | Pod stays Pending (hard) |
| ScheduleAnyway | Soft preference, scores nodes |
4. Using Topology Keys
| Key | Goal |
|---|
topology.kubernetes.io/zone | AZ spread (HA) |
kubernetes.io/hostname | Node spread |
topology.kubernetes.io/region | Region spread |
5. Configuring Label Selectors
labelSelector:
matchLabels: { app: web }
matchExpressions:
- { key: tier, operator: In, values: [frontend] }
6. Setting Match Label Keys
matchLabelKeys: [pod-template-hash] # 1.27+ stable
| Use | Detail |
|---|
| Per-revision spread | Distinct rollouts spread independently |
7. Using Min Domains
minDomains: 3 # require ≥3 zones (1.27+ stable)
whenUnsatisfiable: DoNotSchedule
8. Combining Multiple Constraints
Example: Zone + node spread
topologySpreadConstraints:
- { maxSkew: 1, topologyKey: topology.kubernetes.io/zone, whenUnsatisfiable: DoNotSchedule, labelSelector: { matchLabels: { app: web } } }
- { maxSkew: 1, topologyKey: kubernetes.io/hostname, whenUnsatisfiable: ScheduleAnyway, labelSelector: { matchLabels: { app: web } } }
9. Understanding Node Inclusion Policy
| Field | Effect |
|---|
| nodeAffinityPolicy | Honor / Ignore — filter nodes by pod's affinity before counting |
| nodeTaintsPolicy | Honor / Ignore tainted nodes |
10. Troubleshooting Spread Issues
| Symptom | Cause |
|---|
| Pending FailedScheduling | maxSkew=1 + DoNotSchedule too strict |
| Imbalanced placement | Initial pods skew baseline; use cluster autoscaler |
| Wrong domains counted | Set nodeAffinityPolicy: Honor |