Skip to main content

Topology Spread Constraints

Key Takeaways for AI & Readers
  • High Availability Enforcement: Topology Spread Constraints ensure Pods are evenly distributed across different topological domains (nodes, zones, regions) to prevent single points of failure.
  • Minimizing Skew: The maxSkew parameter allows precise control over the acceptable imbalance of Pods between different topology categories.
  • Granular Control with topologyKey: By specifying topologyKey (e.g., zone, hostname), you dictate the axes along which Pods should be spread.
  • Flexible Scheduling: whenUnsatisfiable modes (DoNotSchedule for strict adherence, ScheduleAnyway for best-effort balancing) provide flexibility based on application criticality.

How do you ensure your application stays online if an entire Data Center goes dark? Even if you have 10 replicas, Kubernetes might accidentally schedule all of them on the same rack or in the same Availability Zone (AZ).

Topology Spread Constraints allow you to control how Pods are distributed across your cluster to achieve true high availability.

1. Balancing the Load​

The goal is to minimize "Skew"—the difference in pod count between different zones.

Topology Spread

maxSkew: 1 | whenUnsatisfiable: DoNotSchedule
AZ-A
0 Pods
AZ-B
0 Pods
AZ-C
0 Pods
Kubernetes ensures the difference between the minimum and maximum count in each zone is never greater than maxSkew.

2. Key Parameters​

maxSkew​

The maximum degree to which pods may be unevenly distributed. A maxSkew of 1 means the difference between the most-populated zone and the least-populated zone cannot be more than 1.

topologyKey​

The label key of the nodes.

  • topology.kubernetes.io/zone: Spread across AZs.
  • kubernetes.io/hostname: Spread across individual nodes (like Anti-Affinity).

whenUnsatisfiable​

  • DoNotSchedule (Hard): The scheduler will stay in Pending if it can't find a node that satisfies the skew.
  • ScheduleAnyway (Soft): The scheduler will try its best to balance, but will schedule the pod anyway if it has to.

3. Comparison with Anti-Affinity​

  • Pod Anti-Affinity: Is binary. "One pod per node, or zero."
  • Topology Spread: Is granular. "You can have many pods per node, but keep the zones balanced."