DevOps Dictionary

Kubernetes Pod Topology Spread Constraints are scheduling rules that tell Kubernetes to distribute matching pods across topology domains, such as availability zones, nodes, or racks. In practical terms, they help you avoid placing too many replicas of the same workload in one failure domain.

What pod topology spread constraints do

Topology spread constraints reduce placement skew. Instead of letting the scheduler pack replicas wherever resources are available, you can ask it to keep pods balanced across a chosen topology.

Common topology domains include:

• Nodes: using kubernetes.io/hostname
• Availability zones: using topology.kubernetes.io/zone
• Regions: using topology.kubernetes.io/region
• Custom domains: using your own node labels, such as rack or node-pool

This is useful for highly available services, batch workers, ingress controllers, and stateful applications where replica placement affects reliability.

How it works

You define topology spread constraints in a pod spec, usually inside a Deployment, StatefulSet, Job, or ReplicaSet template. The Kubernetes scheduler then compares how many matching pods already run in each topology domain and places new pods according to your rule.

The main fields are:

• topologyKey: the node label that defines the domain, such as topology.kubernetes.io/zone.
• maxSkew: the maximum allowed difference in matching pod counts between domains.
• whenUnsatisfiable: what Kubernetes should do if the rule cannot be met. Use DoNotSchedule for strict placement or ScheduleAnyway for best-effort placement.
• labelSelector: which pods should be counted when calculating skew.
• minDomains: the minimum number of eligible domains required before Kubernetes applies the skew calculation.

Simple example

Suppose you run a Deployment with 6 replicas across 3 availability zones. With topologyKey: topology.kubernetes.io/zone and maxSkew: 1, Kubernetes tries to keep the pods close to 2 per zone.

topologySpreadConstraints:
  - maxSkew: 1
    topologyKey: topology.kubernetes.io/zone
    whenUnsatisfiable: DoNotSchedule
    labelSelector:
      matchLabels:
        app: checkout-api

If one zone already has 3 matching pods and another has 1, the scheduler will prefer the less-populated zone. If DoNotSchedule is set and no valid node can satisfy the rule, the pod stays Pending.

Common use cases

• High availability: spread service replicas across zones so one zone failure does not take down every pod.
• Node-level resilience: spread replicas across nodes to avoid losing many pods when one node drains, fails, or restarts.
• Balanced resource usage: reduce hot spots caused by too many pods from the same workload landing on one node pool.
• Controlled failure domains: use custom node labels to spread pods across racks, hardware classes, or node groups.
• Safer operations: keep workloads available during node maintenance or Kubernetes upgrades.

Topology spread constraints vs pod anti-affinity

Topology spread constraints and pod anti-affinity can both keep pods apart, but they work differently.

• Pod anti-affinity says where pods should not run based on other pods. It is good for strict separation, such as “do not place two replicas on the same node.”
• Topology spread constraints focus on balance. They let you control skew, such as “keep replicas evenly spread across zones with a maximum skew of 1.”

For many modern Kubernetes workloads, topology spread constraints are easier to reason about when you want even distribution rather than absolute separation.

Benefits and tradeoffs

• Benefit: improves workload availability by reducing concentration in one failure domain.
• Benefit: gives platform teams precise control over pod distribution without hard-coding node names.
• Benefit: works with standard Kubernetes labels and controllers.
• Tradeoff: strict constraints can leave pods Pending if the cluster lacks enough eligible nodes or zones.
• Tradeoff: incorrect label selectors can make the scheduler count the wrong pods or no pods at all.
• Tradeoff: spreading pods across zones can increase cross-zone network traffic for chatty services.

Operational notes

Topology spread constraints depend on accurate node labels. Managed Kubernetes services usually apply zone and region labels automatically, but custom topology labels must be maintained by your platform team.

If you manage workloads with infrastructure as code, define these constraints in your Kubernetes manifests or templates. For example, teams that deploy Kubernetes resources using Terraform can include topology spread rules in the rendered Deployment spec.

When deploying applications on Amazon EKS, the same Kubernetes scheduling behavior applies. For example, a workload like Apache Airflow on AWS Elastic Kubernetes Service may use topology spread constraints to keep schedulers, web servers, or workers distributed across nodes or zones.

When to use them

Use pod topology spread constraints when replica placement affects uptime, maintenance safety, or resource balance. Start with zone-level spreading for critical services, then add node-level spreading where needed.

A practical default for many stateless Deployments is:

• topologyKey: topology.kubernetes.io/zone
• maxSkew: 1
• whenUnsatisfiable: ScheduleAnyway for flexible placement, or DoNotSchedule for stricter availability requirements

Choose strict rules carefully. If your cluster has only one eligible zone, limited capacity, or restrictive taints and node selectors, strict topology spread constraints can block scheduling.