How to Use Kubernetes Pod Anti-Affinity to Spread Replicas Across Nodes

The problem with replicas on one node

A Deployment with replicas: 3 looks highly available, but the scheduler has no default preference about which nodes those pods land on. On a small cluster under load, all three replicas can end up on the same node - and a single node failure takes the whole service down at once.

podAntiAffinity fixes this by expressing a scheduling preference: don't place this pod on a node that already runs a pod matching the same label.

Soft vs hard anti-affinity

Kubernetes offers two forms:

• preferredDuringSchedulingIgnoredDuringExecution (soft) - the scheduler tries to spread pods but will still schedule them on the same node if no other option exists. Use this when availability is important but you still need pods to start on a small or under-resourced cluster.
• requiredDuringSchedulingIgnoredDuringExecution (hard) - the scheduler refuses to place the pod if no eligible node exists. Pods go Pending until a suitable node appears. Use this only when co-location is truly unacceptable.

For most workloads the soft form is the right default.

Adding pod anti-affinity to a Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
spec:
  replicas: 3
  selector:
    matchLabels:
      app: api
  template:
    metadata:
      labels:
        app: api
    spec:
      affinity:
        podAntiAffinity:
          preferredDuringSchedulingIgnoredDuringExecution:
          - weight: 100
            podAffinityTerm:
              labelSelector:
                matchLabels:
                  app: api
              topologyKey: kubernetes.io/hostname
      containers:
      - name: api
        image: my-api:latest

Key fields:

• labelSelector.matchLabels - matches the pods' own label (app: api). The rule says "don't land next to another pod that also has app: api."
• topologyKey: kubernetes.io/hostname - defines a node as the unit of separation. Each unique hostname is one topology domain, so the scheduler tries to put each replica on a different physical or virtual node.
• weight: 100 - on the soft form, higher weight means the scheduler scores this preference more heavily when choosing between candidates.

Verify placement after applying

kubectl apply -f deployment.yaml
kubectl get pods -o wide

The NODE column shows which node each pod landed on. On a multi-node cluster, the three replicas should appear on different nodes. On a single-node cluster (or a cluster with fewer nodes than replicas), the soft form still schedules all pods - they just share a node.

When to use topology spread constraints instead

For more precise control over distribution - such as spreading evenly across availability zones or limiting how many pods can share a node - use topologySpreadConstraints. Anti-affinity is a preference rule; topology spread constraints let you set a maxSkew (the max imbalance allowed) and mix DoNotSchedule or ScheduleAnyway policies.