Kubernetes Pod Anti Affinity Placement

Kubernetes Pod Anti Affinity Placement is the inverse of pod affinity: a scheduling mechanism that constrains where a Pod may be placed by requiring or preferring that it not share a topology domain with Pods matching a given label selector, configured through spec.affinity.podAntiAffinity. Where pod affinity pulls related Pods together, anti-affinity pushes them apart — its most common and important use is spreading replicas of the same workload across different nodes or availability zones, so that the failure of a single node or zone does not take down every replica simultaneously.

Anti-affinity uses the same structural building blocks as pod affinity — a labelSelector identifying the Pods to avoid, a topologyKey defining the granularity of separation, and both requiredDuringSchedulingIgnoredDuringExecution and preferredDuringSchedulingIgnoredDuringExecution variants — but the direction of the resulting placement decision is reversed.

Required Anti-Affinity

Hard Separation Guarantees

A required anti-affinity rule filters out any node sharing the specified topology domain with an existing matching Pod, guaranteeing that no two Pods satisfying the mutual anti-affinity relationship ever land in the same domain simultaneously.

affinity:
  podAntiAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
      - labelSelector:
          matchExpressions:
            - key: app
              operator: In
              values: ["codartium-api"]
        topologyKey: "kubernetes.io/hostname"

This guarantees no two Pods labeled app: codartium-api ever run on the same node, providing a hard guarantee against a single node failure taking out multiple replicas simultaneously.

The Risk of Over-Constraining

Because required anti-affinity is a hard filter, a replica count exceeding the number of distinct topology domains available (more replicas than nodes, when using kubernetes.io/hostname as the topology key) will leave some replicas permanently unschedulable — this is a common and easily overlooked failure mode when scaling a Deployment up without accounting for the anti-affinity rule's implicit ceiling on replica count.

Preferred Anti-Affinity

Soft Spreading Without a Hard Ceiling

The far more commonly used variant in production: a weighted preference for spreading replicas apart, without hard-blocking placement if perfect separation is not achievable.

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

This encourages the scheduler to spread codartium-api replicas across distinct nodes wherever possible, while still allowing replicas to co-locate if the cluster genuinely lacks enough distinct nodes to spread every replica perfectly — avoiding the hard-ceiling problem of the required variant while still meaningfully improving fault tolerance in the common case.

Common Topology Keys for Anti-Affinity

Node-Level Separation

kubernetes.io/hostname spreads Pods across distinct physical or virtual machines, protecting against single-node failures — the most common anti-affinity use case for stateless application replicas.

Zone-Level Separation

topology.kubernetes.io/zone spreads Pods across distinct availability zones, protecting against a zone-wide outage taking down every replica of a service — a common requirement for workloads with formal availability SLAs spanning multiple zones.

Anti-Affinity vs. Topology Spread Constraints

When Anti-Affinity Is the Right Tool

Anti-affinity is best suited to relationships between two different labeled groups of Pods, or to simple "never co-locate replicas of this exact workload" requirements — it answers "should this Pod avoid running near Pods matching this selector," which is naturally a pairwise, relational question.

When Pod Topology Spread Constraints Are Preferable

For evenly distributing a single workload's replicas across a specific topology dimension with fine-grained control over acceptable imbalance (maxSkew), Pod Topology Spread Constraints are generally the more precise and purpose-built tool, since anti-affinity was not originally designed to express "spread evenly" so much as "avoid entirely" or "prefer to avoid," and can behave less predictably than topology spread constraints when replica counts significantly exceed available topology domains.

Practical Considerations

Combining with Multiple Replicas

Anti-affinity rules are typically applied identically across every replica of a Deployment via its Pod template, so that the rule applies symmetrically — every replica avoids every other replica matching the same label, not just a designated "primary" avoiding the rest.

Scheduling Performance at Scale

Like pod affinity, anti-affinity requires the scheduler to inspect existing Pod placements rather than simple node labels, carrying a similar computational cost consideration in very large clusters with many Pods and frequent anti-affinity evaluation.

Example

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