Topology Spread Constraints (TSC) are the modern, recommended way to distribute Pods evenly across failure domains — zones, nodes, or any custom topology. They're more flexible and more efficient than Pod anti-affinity for spreading workloads.

1. The Core Idea: maxSkew

A Topology Spread Constraint says: "The difference in Pod count between any two topology domains must not exceed maxSkew."

# The formula:
# skew = (max count in any domain) - (min count in any domain)
# Constraint: skew ≤ maxSkew

# maxSkew=1: perfectly balanced (difference of at most 1)
# maxSkew=2: allows some imbalance (difference of at most 2)
# maxSkew=3: very relaxed (rarely useful)

Basic Spec

spec:
  topologySpreadConstraints:
    - maxSkew: 1                              # Max allowed imbalance
      topologyKey: topology.kubernetes.io/zone # What defines a "domain"
      whenUnsatisfiable: DoNotSchedule        # Hard or soft?
      labelSelector:                          # Which Pods to count
        matchLabels:
          app: web

Fields Explained

2. whenUnsatisfiable — Hard vs Soft

# Hard: 7 replicas, 3 zones, maxSkew=1
# Zone A: 3, Zone B: 2, Zone C: 2 → skew = 3-2 = 1 ✓
# 8th Pod: would make A:4, skew=4-2=2 → BLOCKED (DoNotSchedule)
#          must go to B or C: A:3, B:3, C:2 → skew=1 ✓

# Soft (ScheduleAnyway): same scenario
# 8th Pod: scheduler prefers B or C, but if they're full/unavailable,
# it CAN go to A (skew=2, which exceeds maxSkew, but Pod still schedules)

3. Multiple Constraints (Zone + Node Spreading)

The most common production pattern: spread across zones AND across nodes within each zone:

spec:
  topologySpreadConstraints:
    # Spread across zones (hard):
    - maxSkew: 1
      topologyKey: topology.kubernetes.io/zone
      whenUnsatisfiable: DoNotSchedule
      labelSelector:
        matchLabels:
          app: web
    # Also spread across nodes within each zone (soft):
    - maxSkew: 1
      topologyKey: kubernetes.io/hostname
      whenUnsatisfiable: ScheduleAnyway
      labelSelector:
        matchLabels:
          app: web

4. Practical Patterns

Pattern: Cluster-Wide Default (K8s 1.24+)

Set default topology spread constraints for ALL Pods in the cluster via scheduler configuration:

# In KubeSchedulerConfiguration:
apiVersion: kubescheduler.config.k8s.io/v1
kind: KubeSchedulerConfiguration
profiles:
  - pluginConfig:
      - name: PodTopologySpread
        args:
          defaultConstraints:
            - maxSkew: 3
              topologyKey: topology.kubernetes.io/zone
              whenUnsatisfiable: ScheduleAnyway
            - maxSkew: 5
              topologyKey: kubernetes.io/hostname
              whenUnsatisfiable: ScheduleAnyway
          defaultingType: List    # or "System" for K8s built-in defaults

Pattern: Match Affinity and Spread Together

# Restrict to specific zones + spread evenly within those zones:
spec:
  affinity:
    nodeAffinity:
      requiredDuringSchedulingIgnoredDuringExecution:
        nodeSelectorTerms:
          - matchExpressions:
              - key: topology.kubernetes.io/zone
                operator: In
                values: [us-east-1a, us-east-1b]  # Only these 2 zones
  topologySpreadConstraints:
    - maxSkew: 1
      topologyKey: topology.kubernetes.io/zone
      whenUnsatisfiable: DoNotSchedule
      labelSelector:
        matchLabels:
          app: web
# Result: Pods only in zones a and b, evenly spread between them

Pattern: minDomains — Prevent Concentration

# Problem: If only 1 node exists with the right label, all Pods go there
# minDomains says "consider at least N domains" even if fewer exist now:
spec:
  topologySpreadConstraints:
    - maxSkew: 1
      topologyKey: topology.kubernetes.io/zone
      whenUnsatisfiable: DoNotSchedule
      minDomains: 3                        # Expect at least 3 zones
      labelSelector:
        matchLabels:
          app: web
# If only 2 zones exist → Pod stays Pending (waiting for 3rd zone)
# Prevents deploying all replicas in a degraded topology

Debugging Topology Spread

# Check current distribution:
kubectl get pods -l app=web -o custom-columns=\
NAME:.metadata.name,\
NODE:.spec.nodeName,\
ZONE:.metadata.labels.topology\.kubernetes\.io/zone

# Check scheduler events for spread violations:
kubectl describe pod web-pending
# Events:
#   Warning  FailedScheduling  doesn't satisfy spread constraint:
#   zone skew (3) > maxSkew (1)

Summary