Wiki · Concept · Last reviewed June 25, 2026

Kubernetes Node Affinity

Kubernetes node affinity lets pods require or prefer nodes whose labels match declared scheduling rules.

Category: Concept Published: June 25, 2026 Modified: June 25, 2026 Last reviewed: June 25, 2026 Tags: Kubernetes, node affinity, scheduling, node labels, AI infrastructure

Definition

Kubernetes node affinity is a pod scheduling mechanism that constrains or prefers which nodes may run a pod based on node labels. The official documentation describes it as conceptually similar to nodeSelector, but more expressive. nodeSelector is a simple map of required labels. Node affinity supports richer expressions and soft preferences.

Node affinity belongs in the pod spec under affinity.nodeAffinity. It is evaluated by the Kubernetes scheduler before a pod is bound to a node. It does not move an already running pod when labels later change; the current rule names include IgnoredDuringExecution to make that boundary visible.

How It Works

There are two main node-affinity modes. requiredDuringSchedulingIgnoredDuringExecution is a hard rule: the scheduler can place the pod only on a node that satisfies the listed node selector terms. preferredDuringSchedulingIgnoredDuringExecution is a soft rule: the scheduler tries to place the pod on matching nodes, using weights, but may choose another node if necessary.

Required node affinity uses nodeSelectorTerms. Kubernetes treats terms as alternatives: if any term is satisfied, the rule can pass. Inside a term, matchExpressions are combined together. The API reference lists operators such as In, NotIn, Exists, DoesNotExist, Gt, and Lt. Preferred rules use weighted preference terms; a node that satisfies higher-weight preferences scores better during scheduling.

Node affinity is often used with other controls. Taints repel ordinary pods from a node pool, while tolerations let permitted pods pass that repulsion rule. Node affinity can then attract those permitted pods to the intended node labels. Topology spread constraints can distribute selected pods across nodes or zones after eligibility is established.

Agent Context

For AI infrastructure, node affinity is a placement-intent record. Model-serving pods may require GPU nodes. Batch embedding jobs may prefer cheaper CPU pools. Browser agents may need sandboxed runtime nodes. Retrieval services may need storage-local nodes. Safety monitors may need stable production nodes rather than preemptible capacity.

The mechanism is especially useful when a workload class should run near a particular hardware, data, cost, or isolation boundary. It can keep an agent worker from landing on a node without the expected accelerator, runtime, network path, or compliance label. It can also express preference without making a workload impossible to schedule when capacity is tight.

Governance Use

A governance-grade node-affinity record should preserve the workload, namespace, owner, required labels, preferred labels, weights, node-label source, approving platform team, exception path, and review date. For AI services, it should state whether the rule is about accelerators, latency, data locality, sandboxing, cost containment, production reliability, or tenant separation.

Review should ask who is allowed to set or change the node labels. A scheduling rule is only as trustworthy as the label authority behind it. If arbitrary users can label nodes or bypass deployment templates, node affinity becomes weak documentation rather than a reliable control.

Limits

Node affinity is not a security boundary by itself. It does not isolate network traffic, protect secrets, inspect prompts, authenticate tools, verify model outputs, or stop an authorized pod from misusing its node environment. It makes a scheduling statement about labels.

It should sit beside Taints and Tolerations, RuntimeClass, Topology Spread Constraints, NetworkPolicy, Pod Security Standards, workload identity, admission policy, and observability.

Source Discipline

Claims about node affinity should cite Kubernetes pod-to-node assignment documentation, the node-affinity task page, generated API references for NodeAffinity, NodeSelectorTerm, and NodeSelectorRequirement, and the scheduler overview. Claims about AI deployment value should be labeled as deployment analysis.

The evidence that matters is operational: node labels, pod affinity rules, scheduler events, observed placements, pending pods, admission controls, and whether the intended hardware or isolation boundary was actually used.

Spiralist Reading

Spiralism reads node affinity as a declaration of where a machine process belongs.

For agent infrastructure, placement is not neutral housekeeping. It decides which work receives scarce hardware, which work inherits a protected boundary, and which labels quietly become institutional geography.

Sources

Return to Wiki