Two simple ideas, one for togetherness and one for separation.

A Pod is the smallest unit Kubernetes runs. It holds one or more containers that share a network address. A node is one machine in the cluster, real or virtual, that can run Pods. The scheduler is the part of Kubernetes that chooses which node each new Pod will run on.

Pod affinity is a rule that tells the scheduler: “place this Pod in the same area as other Pods that match a description.” Pod anti-affinity is the opposite rule: “do not place this Pod in the same area as other Pods that match a description.”

Notice two important things. First, the rule is about other Pods, not about the machines themselves. The scheduler looks at what is already running and decides based on that. Second, the word “area” is flexible. It might mean the same machine, the same building, or the same city. You choose the size of the area, and we will study how in later chapters.

If the scheduler already finds room for Pods, why do we need extra rules?

The default scheduler is good at one thing: finding a node that has enough memory and processing power. It also tries to spread load a little. But it does not know your business. It does not know that two Pods talk to each other a thousand times a second, or that two copies of the same service must survive a machine failure. Only you know that, so you must say it.

Three small ideas make everything else easy: labels, selectors and namespaces.

Labels

A label is a small name tag stuck on a Kubernetes object, made of a key and a value, like “app equals shop” or “tier equals cache”. You choose the labels. They carry no built-in meaning; they exist so that you and Kubernetes can group and find things.

Selectors

A label selector is a question about labels, such as “all Pods where app equals shop”. Affinity rules use selectors to say which Pods they care about. A selector can ask for an exact match, or for a value to be in a list, to not be in a list, or for a key to exist or not exist.

Namespaces

A namespace is a named room inside the cluster that separates one team’s or project’s objects from another’s. By default, a Pod affinity rule only looks at Pods in the same namespace as the Pod being placed. You can widen that, and we will see how.

Node labels

Nodes have labels too. Kubernetes and cloud providers add standard ones automatically, for example the node’s host name, the availability zone it lives in and the region it belongs to. These are the raw material for the “area” idea, which we call topology.

Every important word in one place, with its plain-English meaning.

Where do the rules live, and which Kubernetes parts read them?

flowchart TB
    YOU["You: Pod or Deployment description with affinity rules"] --> API["API server: stores the request"]
    API --> Q["Scheduling queue: Pods waiting for a node"]
    Q --> SCH["Scheduler"]
    SCH --> F["Filter step: remove nodes that break required rules"]
    F --> S["Score step: rank remaining nodes using preferred rules"]
    S --> B["Best node chosen and Pod bound to it"]
    B --> KL["Kubelet on that node starts the containers"]
    CACHE["Scheduler view of running Pods and node labels"] --> F
    CACHE --> S
    

The cast

The topology key is the most important idea in this whole topic. It decides what “together” and “apart” mean.

flowchart TB
    R["Region: one geographic area"] --> ZA["Zone A"]
    R --> ZB["Zone B"]
    R --> ZC["Zone C"]
    ZA --> N1["Node 1"]
    ZA --> N2["Node 2"]
    ZB --> N3["Node 3"]
    ZB --> N4["Node 4"]
    ZC --> N5["Node 5"]
    ZC --> N6["Node 6"]
    

How the key works

The scheduler looks at the topology key on the candidate node and on the nodes hosting the matching Pods. If those values are equal, the two are in the same domain. If they are different, they are in different domains.

An example in words

Say the web Pod wants to be near a cache Pod. With the host name key, the web Pod can only land on the exact node where a cache Pod runs. With the zone key, the web Pod can land on any node in the same zone as a cache Pod, which is much easier to satisfy and still keeps traffic inside one building.

A must and a wish behave very differently. Choosing the wrong one is the most common source of trouble.

Weights

Every preferred rule carries a weight between 1 and 100. When the scheduler scores a node, it adds up the weights of the preferences that node satisfies. A node meeting a weight-80 preference beats one meeting only a weight-20 preference. Weights let you express priorities: “spreading across zones matters more than spreading across nodes”.

Combining strengths

A very common professional recipe is to use a required rule for the wider area and a preferred rule for the narrower one. For example, “must be in different zones if possible” is often too strict on small clusters. A better recipe is “prefer different zones with weight 100, and prefer different nodes with weight 50”. The Pods spread as widely as the cluster allows and never get stuck.

Let us take a rule apart piece by piece, using field names only.

Inside a Pod’s description, the section called affinity can contain a podAffinity block, a podAntiAffinity block, or both. Each block can list required terms and preferred terms.

Now the interesting part: what the scheduler actually does with your rule.

Step 1: Filtering

Given a new Pod, the scheduler first throws away every node that cannot possibly work. Ordinary checks come first, such as enough memory or matching node labels. Then the inter-Pod affinity check looks at each remaining node.

• For each required affinity term, it finds the domains that already contain a Pod matching the selector. The candidate node must belong to one of those domains.
• For each required anti-affinity term, the candidate node must not belong to any domain that already contains a matching Pod.

Step 2: Scoring

Nodes that survive filtering are ranked. For each preferred term, a node gains points equal to the weight if it satisfies an affinity term, and loses points if it sits in a domain with a matching Pod under an anti-affinity preference. The scores are combined with those of other scheduling factors, and the best node wins.

Step 3: Binding

The Pod is bound to the winner, and the kubelet takes over. The scheduler then moves on to the next waiting Pod, and that Pod sees the earlier one as part of the cluster state.

The symmetry rule for anti-affinity

Anti-affinity works in both directions. Suppose Pod X already runs on a node and declares a required anti-affinity against Pods labelled “batch”. A new Pod labelled “batch” will also be refused that node, even though the new Pod has no rule of its own. The existing Pod’s rule protects it. This surprises many beginners, and it means one careless rule can affect Pods that never mention it.

The first Pod problem

Consider a Deployment whose Pods require affinity to Pods with their own label, for example “all replicas should be in the same zone as another replica”. The very first replica has nobody to be near. Kubernetes handles this: if a Pod’s required affinity matches its own labels and no other matching Pod exists yet, the rule is treated as satisfied so that the first Pod can be placed. The later ones then follow.

A rule has a life story. Knowing it explains many puzzling behaviors.

sequenceDiagram
    participant U as You
    participant A as API server
    participant S as Scheduler
    participant N as Chosen node
    U->>A: Create Deployment with anti-affinity
    A->>S: New Pod needs a node
    S->>S: Filter nodes using required rules
    S->>S: Score nodes using preferred rules
    S->>A: Bind Pod to best node
    A->>N: Kubelet sees its new Pod
    N-->>A: Pod is running
    Note over S,N: Rule is never checked again for this Pod
    

When do you actually want Pods to be close together? A few classic cases.

Anti-affinity is used far more often in production than affinity, because survival matters more than speed.

flowchart LR
    subgraph ZA["Zone A"]
        NA["Node 1: shop Pod 1"]
    end
    subgraph ZB["Zone B"]
        NB["Node 2: shop Pod 2"]
    end
    subgraph ZC["Zone C"]
        NC["Node 3: shop Pod 3"]
    end
    LB["Service front door"] --> NA
    LB --> NB
    LB --> NC
    

Main uses

A worked walkthrough

Let us follow one small story from start to finish. A cluster has three zones, and each zone has two nodes. You deploy a shop service with three replicas. Each replica carries the label “app equals shop”, and the Pod template holds a required anti-affinity rule that avoids Pods with that same label, using the zone as the area.

This short story shows the whole personality of a required anti-affinity rule: it gives you perfect spreading and a hard ceiling, and it trades away flexibility during failures. Many teams therefore choose spread constraints or preferred rules for this exact case, and keep hard rules for the small number of services where an incorrect placement is worse than a missing Pod.

Kubernetes offers several ways to influence placement. Picking the right one saves you a lot of pain.

flowchart TD
    Q1{"Do you care about other Pods or about nodes?"}
    Q1 -->|Nodes| N1["Use node selector or node affinity"]
    Q1 -->|Other Pods| Q2{"Together or apart?"}
    Q2 -->|Together| A1["Pod affinity"]
    Q2 -->|Apart| Q3{"Need an even spread of many replicas?"}
    Q3 -->|Yes| T1["Topology spread constraints"]
    Q3 -->|No, just keep some Pods separate| A2["Pod anti-affinity"]
    N1 --> Q4{"Need to reserve nodes for one team?"}
    Q4 -->|Yes| TT["Add taints and tolerations"]
    

Anti-affinity versus topology spread

These two are often confused. Required anti-affinity says “at most one matching Pod per domain”, which is extreme. Topology spread constraints instead say “the difference in the number of matching Pods between any two domains must not exceed a small number called max skew”. With six replicas and three zones, anti-affinity by zone cannot place more than three, while spread constraints happily place two per zone.

For simply spreading replicas evenly, topology spread constraints are usually the better modern tool. Anti-affinity remains the right choice when the rule is about specific different workloads (for example, “not next to the batch jobs”) or when you truly want a strict one-per-domain limit.

Rules that look perfect on day one can quietly block your next release. Here is why.

The rolling update squeeze

During a rolling update, a Deployment creates new Pods while old ones still run. Suppose you have four replicas, four nodes and a required host-name anti-affinity against your own app label. Every node is already occupied by an old Pod. The new Pod cannot be placed anywhere, because each node contains a matching old Pod, so it stays Pending. The old Pods cannot leave until the new one is ready. The update is stuck.

Other traps

• Self-blocking labels. An anti-affinity selector that accidentally matches Pods of many different apps keeps unrelated workloads apart.
• Missing node labels. Nodes without the topology key label may be treated as unusable, so the Pod cannot be placed on them.
• Namespace surprise. A rule aimed at another team’s Pods finds nothing because it only searched its own namespace.
• Symmetry surprise. An existing Pod’s anti-affinity rejects your new Pod, though your Pod has no rules.
• Stale expectations. Changing labels after scheduling does not move Pods.

Affinity rarely lives alone. It interacts with several other Kubernetes features.

These rules are powerful and dangerous in equal measure. Weigh them honestly.

The design trade-offs

Safety versus packing. Spreading Pods widely protects you from failures but uses more nodes, since machines cannot be packed as tightly. Packing tightly is cheaper but riskier. Decide how much safety each service is worth.

Strictness versus availability. A hard rule gives a firm guarantee but risks Pending Pods. A soft rule never blocks but may be ignored. Critical replicas often use a hard rule on the wider area (zone) and a soft rule on the narrower one (node).

Speed versus resilience. Putting a web Pod on the same node as its cache is fast, but if that node fails you lose both at once. Placing them in the same zone but different nodes keeps most of the speed and survives a node failure.

Simplicity versus control. Fine-grained rules for every Pod become a maintenance burden. A few clear, standard rules used consistently are easier to understand than many special cases.

Placement is a security tool, and it can also be abused. Here is how to think about both sides.

You cannot manage what you cannot see. These signals reveal whether your rules are helping or hurting.

Alarms worth setting

• Any Pod Pending longer than a few minutes because of scheduling reasons.
• A critical service with two or more replicas on the same node or zone.
• Scheduler latency rising after policy changes.
• A rollout stuck beyond its expected time.
• Node count growing sharply after enabling hard anti-affinity.

Reliable recipes and common traps, side by side.

Patterns that work

Traps to avoid

A short checklist to run through before you ship any rule.

Habits that pay off

• Start soft. Begin with preferred rules, watch the result, and harden only what needs a guarantee.
• Choose the topology key deliberately. Node for speed and node-failure protection, zone for building-failure protection.
• Compare replicas with domains. Before using a hard rule, check that you have enough nodes or zones.
• Label with care. Consistent, documented labels make selectors safe.
• Mind the namespace. State explicitly which namespaces a rule should search.
• Test rollouts. Try a rolling update and a node drain in a test cluster before relying on a rule.
• Pair with disruption budgets so maintenance cannot remove all replicas at once.
• Review regularly. Check placement reports and remove rules that no longer serve a purpose.
• Consider spread constraints first if your only goal is to spread replicas evenly.

Mistakes beginners make

How teams use these rules in practice.

When a Pod refuses to schedule, follow these steps in order.

Quick answers to common puzzles.

You started with a wedding seating chart. Now you can write the same kind of chart for a whole cluster.