By default Kubernetes places pods wherever there is room, and that is not always what you want.

When you create a pod, Kubernetes has to pick one machine from your cluster to run it. That machine is called a node. Out of the box, the scheduler looks for nodes with enough free CPU and memory and picks a good one. For many simple applications this is perfectly fine, and you never need to think about it again.

However, real systems quickly develop special needs. A machine-learning job needs a node with a graphics card. A database needs fast local disks. A payment service must run only on nodes that are certified for sensitive data. A web application with six copies should not have all six on the same machine, because one hardware failure would take the whole application down. These needs cannot be met by free CPU and memory alone, and that is where affinity and anti-affinity come in.

The two big families of rules

Kubernetes offers two families of placement rules that are often confused. Node affinity is about the relationship between a pod and the labels on a node, such as “run me only on nodes that have an SSD.” Pod affinity and pod anti-affinity are about the relationship between a pod and other pods that are already running, such as “run me near the cache pods” or “do not run me on a node that already has one of my siblings.” Knowing which family you need is the first step to using them well.

Every placement rule you write is read by a component that works in two stages.

The Kubernetes scheduler is a control-plane component that watches for new pods that have no node assigned. For each such pod, it goes through a process with three main phases. First it filters out the nodes that cannot run the pod. Then it scores the remaining nodes to find the best one. Finally it binds the pod to the winner by writing the chosen node name onto the pod.

flowchart TD
    A[New pod with no node] --> B[Filtering phase
remove nodes that cannot run the pod]
    B --> C{Any node left?}
    C -->|No| D[Pod stays Pending
event explains why]
    C -->|Yes| E[Scoring phase
rank remaining nodes]
    E --> F[Pick highest score]
    F --> G[Bind pod to node]
    G --> H[Kubelet on node starts containers]
        

Where affinity plugs in

The two strengths of affinity rules map neatly onto the two phases. A required rule works during filtering: a node that does not satisfy it is removed from the list, and if no node satisfies it the pod waits. A preferred rule works during scoring: nodes that satisfy it get extra points, but nodes that do not are still allowed. This single idea, hard filter versus soft score, explains almost all the behaviour you will ever see.

Every affinity rule is just a question asked about labels.

A label is a simple key and value pair attached to a Kubernetes object. A node might carry a label saying its disk type is ssd, another saying its hardware team is gpu-pool, and another saying it lives in a certain zone. Pods carry labels too, for example an application name and a tier. Affinity rules do not know anything about hardware or software directly; they only compare these labels.

Well-known labels that already exist

Kubernetes and cloud providers automatically add several standard labels to nodes. These include the node’s own host name, its operating system, its processor architecture, its instance type, and the region and zone it lives in. Because they are standardized, rules written against them are portable between clusters. You can add your own labels on top for things such as disk type, hardware pools, compliance level, or team ownership.

The oldest and simplest way to steer a pod toward certain nodes.

Before affinity existed, Kubernetes offered a field called nodeSelector. You list one or more label pairs, and the pod can run only on nodes that have all of them. It is easy to read, easy to explain, and works exactly as it sounds. For many small clusters and quick needs, it is still the right tool.

What nodeSelector cannot do

nodeSelector has firm limits. It can only demand an exact match of a label value. It cannot say “this or that,” it cannot say “anything but this,” it cannot express a soft preference, and it cannot refer to other pods. Every entry is a hard requirement, and all entries must be satisfied together. When your needs grow beyond that, you move on to node affinity, which is a strict superset of what nodeSelector can express.

A richer way of telling the scheduler which nodes a pod likes, needs, or dislikes.

Node affinity is a set of rules inside the pod specification that describes how a pod relates to node labels. It grows nodeSelector in three ways. It supports several operators instead of only equality. It allows rules to be soft preferences as well as hard requirements. And it lets you combine conditions in flexible ways so that a pod may be happy with one of several kinds of node.

What “IgnoredDuringExecution” means

Both rule types have the words “IgnoredDuringExecution” at the end of their long field names. This is Kubernetes telling you that the rule is checked only when the pod is being scheduled. Once the pod is running, if the node labels change so that the rule is no longer satisfied, the pod is left alone and continues to run. A variant that would evict such pods was discussed by the community, but it is not implemented, so you should plan as though it does not exist.

sequenceDiagram
    participant U as User
    participant API as API Server
    participant S as Scheduler
    participant N as Chosen Node
    U->>API: Create pod with node affinity rules
    API->>S: Pod is unscheduled
    S->>S: Filter using required rules
    S->>S: Score using preferred rules
    S->>API: Bind pod to best node
    API->>N: Kubelet starts containers
    Note over N: Later label changes do not move the pod
        

Choosing the right strength is the most important design decision you make.

A required rule is a promise that the pod will never run on an unsuitable node, but it comes with a risk: if no suitable node exists, the pod waits forever. A preferred rule keeps your pod running almost anywhere, but gives no guarantee. Good engineers use required rules only for things that would cause real harm if violated, and preferred rules for everything that is merely nicer.

How weights work

Each preferred rule has a weight between one and one hundred. For every node, the scheduler adds up the weights of all preferred rules that node satisfies. This sum becomes part of the node’s overall score, alongside scores from other scheduling considerations such as resource balance. A higher weight means the rule matters more when compared to other rules and other scoring factors.

Six operators, and two simple rules about combining them.

Node affinity rules are built from match expressions. Each expression has a label key, an operator, and, for most operators, a list of values. The operator decides what kind of question is being asked. Learning the six operators is like learning six verbs, and with them you can say almost anything about node labels.

How conditions combine: AND inside, OR outside

Node affinity has a two-level structure that trips up many learners. A required rule contains a list of node selector terms. Each term contains a list of match expressions. Expressions inside one term are combined with AND: all of them must be true. The terms themselves are combined with OR: it is enough for any single term to be satisfied.

flowchart TD
    R[Required node affinity] --> T1[Term 1]
    R --> T2[Term 2]
    T1 --> E1[Expression A
zone In east-1]
    T1 --> E2[Expression B
disk In ssd]
    T2 --> E3[Expression C
pool Exists]
    E1 -. AND .- E2
    T1 -. OR .- T2
    N{Node eligible if
Term 1 fully true
OR Term 2 fully true}
    T1 --> N
    T2 --> N
        

Matching fields as well as labels

Besides labels, a term can match certain fields of the node object itself, most usefully the node name. This is rarely needed, because pinning a pod to one exact machine defeats the purpose of a scheduler, but it can be handy for debugging or for one-off maintenance tasks. Match fields work like match expressions and sit in the same terms.

Keeping pods away from certain nodes using negative operators.

Kubernetes does not have a separate node anti-affinity field. Instead, you create the same effect by using the negative operators, NotIn and DoesNotExist, inside a node affinity rule. “Do not run on nodes labelled as experimental” becomes a rule that says the experimental label does not exist, or that its value is not in a list. The result is a pod that avoids those nodes while remaining free to use all others.

Required and preferred negatives

Negative operators can be used with either strength. A required negative is a strict exclusion: the pod will never run on a node with the unwanted label. A preferred negative simply lowers the appeal of such nodes, so the pod lands there only when better options are exhausted. This difference is important for cost control, where you might prefer to avoid expensive nodes without making the application fail when they are the only ones left.

Rules about neighbours: who to sit next to, and who to avoid.

Node affinity looks at node labels. Pod affinity and pod anti-affinity look at the labels of pods that are already running. A pod affinity rule says “place me in the same area as pods that match this description.” A pod anti-affinity rule says “do not place me in the same area as pods that match this description.” The word area is precise: it is defined by a topology key, which we explore in the next chapter.

Required and preferred work the same way

Pod affinity and anti-affinity also come in required and preferred forms, with the same filtering and scoring meaning as before. A required anti-affinity rule is a strict guarantee of spreading, but it makes the number of schedulable copies depend on the number of available domains. A preferred anti-affinity rule spreads pods as much as reasonably possible, but happily doubles up when the cluster is small or busy.

One label name decides the size of the neighbourhood for every pod affinity rule.

The topology key is the name of a node label. Nodes that share the same value for that label form one topology domain. When a pod affinity rule says “same domain as pods matching X,” it means “on a node whose value for the topology key equals that of a node running a pod matching X.” Changing the key changes the meaning of “together” without touching anything else in the rule.

graph TD
    subgraph Region
        subgraph Zone A
            N1[Node 1
host-1]
            N2[Node 2
host-2]
        end
        subgraph Zone B
            N3[Node 3
host-3]
            N4[Node 4
host-4]
        end
    end
    H[Key = host name
every node is its own domain] -.-> N1
    Z[Key = zone
Node 1 and 2 share a domain
Node 3 and 4 share a domain] -.-> N2
        

Choosing the right size of neighbourhood

Spreading over host names protects you from single-machine failures. Spreading over zones protects you from the loss of an entire data-centre zone, which is a rarer but more serious event. Many production services use both: a required or strongly weighted rule at the zone level for the big protection, and a softer rule at the host name level for tidy distribution within each zone.

Kubernetes offers several ways to influence placement, and each has its own strengths.

Affinity is only one member of a family of scheduling controls. Choosing the right member for the job keeps your configuration simple and predictable. The most common confusion is between affinity, which attracts pods, and taints and tolerations, which repel them from the node side.

Taints versus affinity: a key difference

A taint is a mark placed on a node that repels every pod that does not carry a matching toleration. A toleration on a pod only says “I am allowed on that node.” It does not say “I want to be there.” So a toleration alone never pulls a pod toward a tainted node. To reserve a group of nodes for one workload, you normally use both: a taint on the nodes to keep everyone else out, and node affinity on the pods to attract them in.

Topology spread constraints versus pod anti-affinity

Pod anti-affinity says “not with these pods,” which is a blunt instrument for spreading. Topology spread constraints say “keep the difference between the busiest and emptiest domain within a chosen limit,” which produces a balanced layout and allows more copies than there are domains. For pure even spreading, spread constraints are usually the better and cheaper tool, while anti-affinity remains ideal for saying “keep these specific workloads apart.”

Real situations and the rule that fits them best.

Situations that call for node affinity

Situations that call for pod affinity

Situations that call for pod anti-affinity

Rules that look perfect on a quiet day can misbehave when the cluster is busy changing.

Rolling updates and required anti-affinity

During a rolling update, Kubernetes may create extra pods before removing old ones. If a required anti-affinity rule forbids two copies on the same node, and every node already holds one copy, the extra pod has nowhere to go. It stays Pending, the rollout stalls, and the release stops making progress. The usual remedies are to keep some spare nodes, to allow the rollout to remove an old pod before adding a new one, or to use a preferred rule where strictness is not truly needed.

sequenceDiagram
    participant D as Deployment
    participant S as Scheduler
    participant N as Nodes (3 nodes, 3 pods)
    D->>S: Create surge pod for new version
    S->>N: Filter with required anti-affinity
    N-->>S: Every node already hosts a copy
    S-->>D: No node available
    Note over D: Surge pod stays Pending
    Note over D: Rollout waits until an old pod is removed or a node is added
        

Autoscaling and node provisioning

Cluster autoscalers look at Pending pods and decide whether adding a node would help. A pod that is Pending because of a required affinity rule can trigger the creation of a new node, but only if that new node would satisfy the rule. If the rule asks for a label that new nodes do not receive, more machines will not help. Make sure your node pools carry the labels your rules depend on.

Maintenance and draining

When a node is drained for maintenance, its pods are evicted and recreated elsewhere, and the scheduler applies all rules again to find new homes. Tight rules can leave evicted pods with no place to go. Planning capacity with maintenance in mind, meaning always having some spare room in each zone, keeps drains from turning into outages.

Not all rules cost the same for the scheduler to evaluate.

Node affinity is relatively cheap. For each pod, the scheduler looks at each node’s labels and checks a few conditions. The work grows in step with the number of nodes and is easy to handle even in very large clusters. This is why node affinity and nodeSelector are considered safe at almost any scale.

Pod affinity and anti-affinity are more expensive. To evaluate them, the scheduler must consider all existing pods that match the selector and work out which domains they occupy, for every candidate node. The cost grows with both the number of pods and the number of nodes, and the official guidance warns that these rules can slow scheduling noticeably in clusters with several hundred nodes. For very large clusters, topology spread constraints often achieve the same goal at lower cost.

Placement rules can protect workloads, but only if the labels themselves can be trusted.

Affinity is frequently used to isolate sensitive workloads, for example keeping payment services on nodes reserved for that purpose. This only works if two conditions hold: no untrusted pod can land on those nodes, and no untrusted party can change the labels those rules rely on. Otherwise the rule is a polite suggestion rather than a security control.

When a pod will not start, the cluster usually tells you exactly why, if you know where to look.

The most common symptom of an affinity problem is a pod stuck in the Pending state. The scheduler records a message in the pod’s events that lists how many nodes were rejected and for what reason. Reading that message carefully solves most cases quickly, because it tells you whether the problem is node labels, pod affinity, anti-affinity, taints, or plain lack of resources.

What to monitor over time

Proven combinations that solve recurring problems.

flowchart TD
    Q1{What do you need?} -->|Right kind of machine| NA[Node affinity]
    Q1 -->|Near other pods| PA[Pod affinity]
    Q1 -->|Away from other pods| PAA[Pod anti-affinity]
    Q1 -->|Even distribution| TS[Topology spread constraints]
    Q1 -->|Reserve nodes| TT[Taints + tolerations + node affinity]
    NA --> S1{Is it truly mandatory?}
    PA --> S1
    PAA --> S1
    S1 -->|Yes| RQ[Use required]
    S1 -->|No| PR[Use preferred with weight]
        

Habits that create stuck pods, stalled rollouts, and confusing clusters.

A short checklist to keep placement rules understandable and safe.

How teams apply these ideas in everyday operations.

nodeSelector only supports exact label matches, and every entry is mandatory. Node affinity supports several operators, alternatives, and soft preferences with weights. Anything nodeSelector can do, node affinity can do too.

Not as a distinct field. You express it with the NotIn and DoesNotExist operators inside node affinity. Pod anti-affinity, on the other hand, is a named feature for keeping pods apart from other pods.

The pod stays Pending and the scheduler keeps retrying. An event on the pod explains how many nodes were rejected and why. The pod starts when a suitable node appears.

No. Rules are evaluated only when the pod is scheduled, which is what the words IgnoredDuringExecution mean. Running pods stay where they are until they are restarted or evicted for another reason.

Terms are combined with OR, so a node needs to satisfy only one. Expressions within a single term are combined with AND, so all of them must be true.

It sets how many points a node earns for satisfying that rule, from one to one hundred. The scheduler sums the weights for each node and adds them to its other scores, so higher weights make the rule matter more.

Placement rules, taints, or volume constraints may be rejecting those nodes. Read the scheduling event on the pod, which normally lists the reasons and how many nodes each affected.

It is the name of a node label that defines what counts as the same place for pod affinity and anti-affinity. Using the host name means the same node, and using the zone means the same zone.

For an even spread across many domains, topology spread constraints are usually simpler and cheaper. For keeping specific workloads apart from each other, or for strict one-per-domain rules, pod anti-affinity is the right fit.

No. A toleration only allows a pod to run on a tainted node. To draw pods in, add a node affinity rule that prefers or requires that node group.

By default they consider only pods in the same namespace as the pod being scheduled. You can widen the scope with a namespace list or a namespace selector.

Node affinity is cheap, but pod affinity and anti-affinity become costly in large clusters because the scheduler must compare many pods against many nodes. Keep selectors narrow and consider spread constraints at scale.

Affinity and anti-affinity are the vocabulary Kubernetes gives you for telling the scheduler where pods belong. Node affinity speaks about node labels, letting you attract pods to the right kind of machine and, with negative operators, keep them away from the wrong kind. Pod affinity and pod anti-affinity speak about neighbours, letting you place related pods close together or spread copies apart, with the topology key defining how large a neighbourhood is.

The most important idea is the difference between required and preferred. Required rules filter nodes and can leave pods Pending, while preferred rules only adjust scores and always allow the pod to run. Because rules are applied only at scheduling time, they need to be paired with sensible capacity planning, taints for reserving nodes, protected labels for security, and monitoring for stuck pods. Used with care, these tools make your applications resilient, efficient, and predictable.