Prevent Pods from Scheduling
on the Same Node — topologySpreadConstraints

When you scale a Deployment to multiple replicas, Kubernetes decides where each pod lands. Without any constraints, the scheduler may place all replicas on the same node — repeatedly.

Understanding these four building blocks makes the YAML configuration obvious rather than mysterious.

Supported topologyKey Values

• Kubernetes 1.19+ — topologySpreadConstraints became GA (stable) in v1.19
• Multiple nodes — spreading has no effect on a single-node cluster
• Pod labels set correctly — the labelSelector must match your pod labels exactly
• kubectl access — or Helm if using the chart-based approach

Add topologySpreadConstraints directly inside your Deployment manifest under spec → template → spec.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 6
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
        spread-group: "app"    # ← required for labelSelector
    spec:
      # ──────────────────────────────────────────
      # ADD THIS BLOCK under spec (pod spec level)
      # ──────────────────────────────────────────
      topologySpreadConstraints:
        - maxSkew: 3
          topologyKey: "kubernetes.io/hostname"
          whenUnsatisfiable: "ScheduleAnyway"
          labelSelector:
            matchLabels:
              spread-group: "app"
      containers:
        - name: my-app
          image: my-app:latest

Multi-Constraint Example (Node + Zone)

You can stack multiple constraints to spread across both zones and individual nodes simultaneously:

topologySpreadConstraints:
  # Constraint 1: spread across availability zones
  - maxSkew: 1
    topologyKey: "topology.kubernetes.io/zone"
    whenUnsatisfiable: "DoNotSchedule"
    labelSelector:
      matchLabels:
        spread-group: "app"
  # Constraint 2: also spread across individual nodes
  - maxSkew: 2
    topologyKey: "kubernetes.io/hostname"
    whenUnsatisfiable: "ScheduleAnyway"
    labelSelector:
      matchLabels:
        spread-group: "app"

For Helm-managed deployments, parameterize the constraints via values.yaml so they can be tuned per environment without touching the template.

spec:
  template:
    metadata:
      labels:
        spread-group: "{{ .Values.podSpread.label }}"
    spec:
      topologySpreadConstraints:
        - maxSkew: {{ .Values.podSpread.maxSkew }}
          topologyKey: {{ .Values.podSpread.topologyKey }}
          whenUnsatisfiable: {{ .Values.podSpread.whenUnsatisfiable }}
          labelSelector:
            matchLabels:
              spread-group: "{{ .Values.podSpread.label }}"

podSpread:
  maxSkew: 3
  topologyKey: "kubernetes.io/hostname"
  whenUnsatisfiable: "ScheduleAnyway"
  label: "app"

# Production: stricter HA requirements
podSpread:
  maxSkew: 1
  topologyKey: "kubernetes.io/hostname"
  whenUnsatisfiable: "DoNotSchedule"
  label: "app"

# Deploy with production values:
helm upgrade --install my-app ./chart \
  -f values.yaml \
  -f values-prod.yaml

This is mandatory and the most commonly missed step. The labelSelector in your constraint only works if your pods actually have the matching label. Without it, Kubernetes has no idea which pods to count when calculating spread.

# This label MUST exist on every pod you want to spread
metadata:
  labels:
    app: my-app
    spread-group: "app"    # ← this is what labelSelector matches

maxSkew is the core numeric parameter that controls how uneven the distribution can be. It represents the maximum allowed difference in pod count between any two topology domains (nodes).

Example with 3 Nodes and maxSkew: 3

✓ Allowed Distribution

Example with 3 Nodes — Exceeds maxSkew: 3

✗ Not Allowed (Strict Mode)

maxSkew Quick Reference

This field controls what Kubernetes does when it cannot satisfy the spread constraint — either because there aren't enough nodes, or because all valid nodes would violate maxSkew.

topologySpreadConstraints:
  - maxSkew: 1                         # strict balance
    topologyKey: "kubernetes.io/hostname"
    whenUnsatisfiable: "DoNotSchedule"   # hard constraint
    labelSelector:
      matchLabels:
        spread-group: "app"

A common point of confusion: what happens when the same label exists in multiple namespaces?

# If you deploy app with same labels in 2 namespaces:
Namespace A: pods on Node1(3), Node2(1), Node3(2) → balanced ✓
Namespace B: pods on Node1(4), Node2(0), Node3(0) → balanced ✓ (within B)

# Node1 might end up with 3+4 = 7 pods total
# Neither namespace's constraint prevents this
# ❌ topologySpreadConstraints does NOT account for this

When a new pod needs to be scheduled, the Kubernetes scheduler runs through this logic for each topologySpreadConstraint:

# After placing pod on candidate node:
skew = (count_on_candidate + 1) - min_count_across_all_nodes

# If skew > maxSkew → node is ineligible

• Use maxSkew: 1 for strict HA setups where every pod must land on a different node
• Use DoNotSchedule for production-critical apps — never let the scheduler ignore the constraint
• Combine with podAntiAffinity for even stronger node separation (belt + suspenders approach)
• Ensure you have at least as many eligible nodes as replicas when using DoNotSchedule
• Test your spread with kubectl get pods -o wide to verify node distribution after deploy
• For multi-AZ clusters, stack two constraints: one for hostname, one for zone

Combining with podAntiAffinity

For the strongest possible node separation, combine topologySpreadConstraints with a podAntiAffinity rule. The spread constraint handles even distribution; anti-affinity provides a hard barrier.

spec:
  topologySpreadConstraints:
    - maxSkew: 1
      topologyKey: "kubernetes.io/hostname"
      whenUnsatisfiable: "DoNotSchedule"
      labelSelector:
        matchLabels:
          spread-group: "app"

  affinity:
    podAntiAffinity:
      preferredDuringSchedulingIgnoredDuringExecution:
        - weight: 100
          podAffinityTerm:
            labelSelector:
              matchLabels:
                app: my-app
            topologyKey: "kubernetes.io/hostname"

Quick Verification Command

# See which node each pod landed on:
kubectl get pods -l app=my-app -o wide

# Count pods per node:
kubectl get pods -l spread-group=app \
  -o jsonpath='{range .items[*]}{.spec.nodeName}{"\n"}{end}' \
  | sort | uniq -c | sort -rn

With topologySpreadConstraints properly configured, your cluster scheduling is now deterministic and resilient.

Key Takeaways

• Label your pods — spread-group label is mandatory for the constraint to function
• Start with ScheduleAnyway — then tighten to DoNotSchedule once cluster is stable
• maxSkew: 1 for production, maxSkew: 3 for flexible dev/staging environments
• Namespace-scoped by default — cross-namespace spreading is not supported natively
• Stack constraints — combine hostname + zone constraints for multi-AZ resilience
• Verify with kubectl — always confirm actual distribution after deploying