Node Affinity: Tell Your Pods Where to Go

Why it exists

The default Kubernetes scheduler treats all nodes as mostly equal, which is fine for general-purpose workloads. But some workloads need specific hardware or must run in certain locations. Node affinity was created to give developers a flexible way to influence scheduling decisions without hard-coding pod placement to a single, specific node.

The mental model

Think of node affinity as a dating app profile for your pod. The pod spec describes the ideal node it wants to be scheduled on, based on labels. It can have hard requirements ('deal-breakers') like needing a GPU, and soft preferences ('nice-to-haves') like preferring a node in a specific availability zone. The Kubernetes scheduler then plays matchmaker, trying to find the best fit.

How it works

Node affinity rules are defined in a pod's specification and work by matching labels on nodes. There are two main types. First, requiredDuringSchedulingIgnoredDuringExecution is a hard rule; the pod will not be scheduled unless a node with a matching label is found. Second, preferredDuringSchedulingIgnoredDuringExecution is a soft rule; the scheduler will try to find a matching node and give it a higher score, but will schedule the pod elsewhere if no perfect match exists. The 'IgnoredDuringExecution' part means that if a node's labels change after the pod is already running, Kubernetes won't evict the pod.

When to use it

Use node affinity to place pods on nodes with special hardware like GPUs or fast SSDs. It's also essential for controlling pod placement across availability zones for high availability, or keeping pods within a geographic region for data sovereignty and latency reasons. You can also use it to direct workloads to nodes with specific licenses.

When not to use it

Avoid using node affinity for simple, stateless applications that can run anywhere. Overly complex affinity rules can make scheduling difficult, leading to unschedulable pods and an underutilized cluster. For simply repelling pods from certain nodes, taints and tolerations are a better tool. For pinning a pod to one specific node, the simpler nodeSelector field is often sufficient.

One canonical example

To ensure a machine learning pod runs only on a node with a specific GPU, you would add a nodeAffinity rule to the pod spec. This rule would contain a requiredDuringSchedulingIgnoredDuringExecution block that specifies a nodeSelectorTerms matching the label gpu-type=nvidia-a100. If no node in the cluster has this label, the pod will remain in a 'Pending' state until a suitable node becomes available.