By default the scheduler places pods wherever they fit, which can pile every replica into one zone or node. A topology spread constraint distributes pods across a topology domain such as a zone, which keeps an outage from taking all replicas at once.
Before you start
You should be comfortable with Deployments and node labels. This article covers topology spread constraints.
Step-by-step walkthrough
Step 1: Choose the topology domain
topologyKey: topology.kubernetes.io/zone spreads across availability zones, and kubernetes.io/hostname spreads across nodes. The key must match labels the nodes actually carry, or the constraint has no domain to spread across.
Step 2: Set the failure behavior
whenUnsatisfiable: DoNotSchedule is a hard constraint that leaves pods pending if the spread cannot be met, which protects availability but can block scheduling. ScheduleAnyway is a soft preference that spreads when possible but never blocks. Choose based on how strictly you need the spread.
Step 3: Tune maxSkew and minDomains
maxSkew bounds how uneven the distribution may be, and minDomains ensures enough domains exist before enforcing. These control the balance between strict evenness and the ability to schedule during capacity shortfalls.
Worked scenario
The constraint spreads replicas across zones, preferring to.
topologySpreadConstraints:
- maxSkew: 1
topologyKey: topology.kubernetes.io/zone
whenUnsatisfiable: ScheduleAnyway
labelSelector:
matchLabels:
app: apiWalk through the example
The scheduler places api pods so the difference between zones is at most one, spreading load and blast radius. ScheduleAnyway means a zone outage or a shortage never leaves pods unschedulable; it just accepts a less even spread. Changing to DoNotSchedule would enforce evenness at the cost of pending pods.
Common mistake
Using DoNotSchedule with too few nodes or zones, so pods stay pending and the Deployment never reaches its desired count. Another is spreading without labeling nodes with the topology keys, so the constraint has no effect.
Verify the behavior
Create replicas and confirm they are distributed across zones or nodes. Reduce capacity and confirm the soft constraint still schedules. Switch to the hard constraint with limited capacity and observe pending pods.
Interview exercise
When is a hard spread constraint dangerous?
Answer and reasoning
When the cluster does not have enough nodes or zones to satisfy it, because DoNotSchedule leaves pods pending and the workload cannot reach its desired replicas, which reduces capacity exactly when it may be needed. A soft constraint spreads when possible without blocking. Use the hard form only when the spread is a strict availability requirement and capacity is guaranteed.
Continue learning
Compare placement in Node placement and disruption in Pod disruption budgets. Read the Kubernetes topology spread constraints documentation and try the Kubernetes interview questions.