Mastering Kubernetes Pod Topology Spread Constraints: Why Pods Stay Pending

While deploying a component I noticed its pods remained in Pending because the scheduler could not satisfy the pod topology spread constraints that had been added.

What is topologySpreadConstraints ?

It is a field in the Pod spec that controls how pods are distributed across topology domains.

spec:
  topologySpreadConstraints:
  - maxSkew: <integer>
    topologyKey: <string>
    whenUnsatisfiable: <string>
    labelSelector: <object>

For beginners, focus on the four basic fields:

labelSelector : selects pods with matching labels; the scheduler counts matching pods per topology domain.

topologyKey : defines the topology domain, usually a node label such as zone or kubernetes.io/hostname.

maxSkew : the maximum allowed difference in the number of matching pods between domains; a smaller value enforces a more even spread.

whenUnsatisfiable : action when the skew exceeds maxSkew. Options are DoNotSchedule (default) or ScheduleAnyway.

The following diagram illustrates these concepts:

Pod topology constraints can be combined with affinity/anti‑affinity rules for richer scheduling behavior. Example:

affinity:
  podAntiAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
    - labelSelector:
        matchLabels:
          app.kubernetes.io/name: app-server
      topologyKey: kubernetes.io/hostname
schedulerName: default-scheduler
topologySpreadConstraints:
- maxSkew: 1
  topologyKey: topology.kubernetes.io/zone
  whenUnsatisfiable: DoNotSchedule
  labelSelector:
    matchLabels:
      app.kubernetes.io/instance: app-server
      app.kubernetes.io/name: app-server

This configuration prevents pods with matching labels from being placed on the same node (anti‑affinity) while trying to spread them evenly across zones (topology spread). In a two‑node cluster where both nodes belong to the same zone, the constraints cannot be satisfied, so both pods remain Pending.

To resolve the issue, either increase maxSkew to 2 or change whenUnsatisfiable to ScheduleAnyway .