Node affinity controls which nodes a Pod lands on. Pod affinity controls whether a Pod should be co-located with or separated from other Pods. It answers: "Place me near Pods running X" (affinity) or "Keep me away from Pods running Y" (anti-affinity).

1. The Topology Key Concept

Pod affinity doesn't just say "near another Pod" — it defines what "near" means using a topology key. The topology key is a node label that groups nodes into domains.

Common Topology Keys

2. Pod Affinity — "Schedule Near"

Required (Hard)

# "I MUST be in the same zone as a Pod labeled app=cache"
spec:
  affinity:
    podAffinity:
      requiredDuringSchedulingIgnoredDuringExecution:
        - labelSelector:
            matchExpressions:
              - key: app
                operator: In
                values: ["cache"]
          topologyKey: topology.kubernetes.io/zone

Preferred (Soft)

# "I'd LIKE to be on the same node as a Pod labeled app=cache"
spec:
  affinity:
    podAffinity:
      preferredDuringSchedulingIgnoredDuringExecution:
        - weight: 80
          podAffinityTerm:
            labelSelector:
              matchExpressions:
                - key: app
                  operator: In
                  values: ["cache"]
            topologyKey: kubernetes.io/hostname

Use Cases for Pod Affinity

3. Pod Anti-Affinity — "Schedule Away From"

Required — Spread Across Zones

# "I MUST NOT be in the same zone as another Pod with app=web"
spec:
  affinity:
    podAntiAffinity:
      requiredDuringSchedulingIgnoredDuringExecution:
        - labelSelector:
            matchExpressions:
              - key: app
                operator: In
                values: ["web"]
          topologyKey: topology.kubernetes.io/zone
# If you have 3 replicas and 3 zones, each replica lands in a different zone
# If you have 4 replicas and 3 zones → 4th Pod is UNSCHEDULABLE (Pending!)

Required — One Per Node

# "Only one instance of me per node" (like a DaemonSet but with replicas control)
spec:
  affinity:
    podAntiAffinity:
      requiredDuringSchedulingIgnoredDuringExecution:
        - labelSelector:
            matchLabels:
              app: web
          topologyKey: kubernetes.io/hostname
# Ensures at most 1 "app=web" Pod per node
# If replicas > nodes → extra Pods stay Pending

Preferred — Spread Across Nodes (Best Effort)

# "Try to spread across nodes, but don't fail if you can't"
spec:
  affinity:
    podAntiAffinity:
      preferredDuringSchedulingIgnoredDuringExecution:
        - weight: 100
          podAffinityTerm:
            labelSelector:
              matchLabels:
                app: web
            topologyKey: kubernetes.io/hostname
# Scheduler spreads Pods across nodes but will colocate if not enough nodes

Common Anti-Affinity Patterns

4. Scalability Warning

Pod affinity/anti-affinity is expensive for the scheduler. For every Pod being scheduled, the scheduler must check ALL other Pods in the cluster (or namespace) to see which topology domains contain matching Pods.

# Complexity: O(Pods × Nodes)
# With 1000 Pods and 100 nodes, the scheduler evaluates 100,000 combinations
# This is why large clusters see scheduling latency increase with pod affinity

Mitigation Strategies

• Use namespaces field — restrict the search to specific namespaces (instead of all)
• Use namespaceSelector — limit which namespaces are checked
• Prefer Topology Spread Constraints — lighter-weight for spreading (next lesson)
• Use preferred over required — fails gracefully instead of blocking

# Restrict affinity search to specific namespaces:
podAffinity:
  requiredDuringSchedulingIgnoredDuringExecution:
    - labelSelector:
        matchLabels:
          app: cache
      topologyKey: topology.kubernetes.io/zone
      namespaces: ["caching"]         # Only look at Pods in this namespace
      # OR:
      namespaceSelector:
        matchLabels:
          team: platform              # Only namespaces with this label

5. Pod Affinity vs Topology Spread Constraints

Summary

podAffinity:
  requiredDuringSchedulingIgnoredDuringExecution:
    - labelSelector:
        matchLabels:
          app: redis
      topologyKey: topology.kubernetes.io/zone