Node Affinity

Node affinity lets a pod declare which nodes it may or should run on, based on node labels. It is set under spec.affinity.nodeAffinity.

How it works

There are two forms. requiredDuringSchedulingIgnoredDuringExecution is a hard rule: the scheduler will not place the pod unless a node matches. preferredDuringSchedulingIgnoredDuringExecution is a soft rule: the scheduler tries to match but still schedules the pod elsewhere if needed. Preferences carry a weight between 1 and 100.

“IgnoredDuringExecution” means the rules are checked only at scheduling time. If node labels change later, a running pod is not moved.

Matching uses matchExpressions with operators In, NotIn, Exists, DoesNotExist, Gt and Lt. Multiple nodeSelectorTerms are ORed, while several expressions inside one term are ANDed. The simpler nodeSelector field still exists, and if you set both, both must be satisfied.

A practical example

This pod must run in one of two zones:

apiVersion: v1
kind: Pod
metadata:
  name: with-node-affinity
spec:
  affinity:
    nodeAffinity:
      requiredDuringSchedulingIgnoredDuringExecution:
        nodeSelectorTerms: [{matchExpressions: [{key: topology.kubernetes.io/zone, operator: In, values: [eu-west-1a, eu-west-1b]}]}]
  containers: [{name: app, image: nginx}]

Common mistakes

• Using a hard rule where a preference would do, leaving pods Pending when no node matches.
• Mislabelled nodes, so the rule never matches.
• Expecting running pods to be rescheduled when labels change.
• Confusing node affinity with pod affinity and anti-affinity, which relate to other pods rather than node labels.
• Using affinity to keep other workloads off a node. That is the job of taints and tolerations.

When to use it and when not to

Use node affinity to place workloads on suitable hardware, such as GPU nodes, or in particular zones or node pools. For plain label matching, nodeSelector is simpler. To spread replicas evenly, topology spread constraints or pod anti-affinity fit better. With Karpenter, pod affinity and node selectors feed into which nodes get provisioned. See Kubernetes consulting for scheduling design.

See also

• Kubernetes
• Taints and Tolerations
• Karpenter
• Resource Requests and Limits