Node Affinity

This course is built around the public HelixWorks Kubernetes Lab monorepo. The excerpt below is runnable source, not pseudocode.

Source: terraform/main.tf

resource "kind_cluster" "helixworks" {
  name            = var.cluster_name
  node_image      = var.kind_node_image
  wait_for_ready  = true
  kubeconfig_path = local.kubeconfig_path

  kind_config {
    kind        = "Cluster"
    api_version = "kind.x-k8s.io/v1alpha4"

Code to reality

Declared intent

Create the local Kubernetes substrate from versioned infrastructure code.

Interpreter

Terraform builds a dependency graph and the Kind provider calls the Docker and Kind APIs.

Software effect

Terraform records a cluster resource and Kind writes a kubeconfig for its Kubernetes API.

Hardware effect

Docker starts containers that consume the laptop resources used as control-plane and worker nodes.

Observable evidence

terraform state show and kubectl get nodes must agree that the declared cluster is ready.

nodeSelector only does exact-match and can't express "prefer" versus "require". You need richer rules for steering pods toward the right nodes without over-constraining them.

Solution: Use node affinity rules to attract pods to nodes with matching labels (e.g. disktype=ssd), as required or preferred.

A refrigerated cargo ship tells the berth-assignment clerk what kind of dock it needs. If it merely prefers a refrigerated berth, the clerk tries for one but will wave it to any open berth when none is free. If it strictly requires a refrigerated berth, the clerk makes it wait offshore until a cold dock frees up. In Kubernetes the clerk is the scheduler, the ship is a pod with node affinity, a preference is a preferred rule, and a hard requirement is a required rule matched against node labels.

Node affinity is a pod rule the scheduler evaluates against node labels. It pulls a pod toward matching nodes (the opposite of Day 14's taints).

A richer, more expressive way for a pod to choose which nodes it can run on, based on node labels. It's the upgrade to the simple nodeSelector.

   nodeSelector  -> exact match only (disktype=ssd)
   nodeAffinity  -> operators (In, NotIn, Exists...), AND required vs preferred

Keep the mental model straight: taints push pods away, whereas node affinity pulls a pod toward the nodes it prefers.

   Taint/Toleration -> NODE repels pods (permission to land)
   Node Affinity    -> POD is drawn to matching nodes (preference/requirement)

Node affinity comes in a hard form (must match or stay Pending) and a soft form (prefer a match, but run anywhere if none exists).

   requiredDuringSchedulingIgnoredDuringExecution
     = HARD rule. No matching node -> pod stays Pending.

   preferredDuringSchedulingIgnoredDuringExecution
     = SOFT rule. Try to match; if none, schedule anywhere.

   "IgnoredDuringExecution" = once running, label changes won't evict the pod.

The difference comes down to one thing: what the scheduler does when no node matches.

                match node?         no match?
   required:    schedule there      Pending (never runs)
   preferred:   prefer there        runs elsewhere anyway

A required rule is a hard constraint — if no node matches the expression, the pod never schedules.

apiVersion: v1
kind: Pod
metadata:
  name: postgres
spec:
  affinity:
    nodeAffinity:
      requiredDuringSchedulingIgnoredDuringExecution:
        nodeSelectorTerms:
          - matchExpressions:
              - key: disktype
                operator: In
                values: ["ssd"]
  containers:
    - name: postgres
      image: postgres:16
      ports: [{ containerPort: 5432 }]

A preferred rule is best-effort; each preference carries a weight so the scheduler can rank competing soft rules.

  affinity:
    nodeAffinity:
      preferredDuringSchedulingIgnoredDuringExecution:
        - weight: 1                 # 1-100; higher = stronger preference
          preference:
            matchExpressions:
              - key: zone
                operator: In
                values: ["us-east-1a"]

Match expressions support several operators for comparing a node label against your criteria.

   In        label value is in the list
   NotIn     label value is NOT in the list  (anti-affinity-ish)
   Exists    label key exists (any value)
   DoesNotExist  label key absent
   Gt / Lt   greater/less than (numeric)

Affinity matches on node labels, so first tag the nodes you want to target.

kubectl label node cka-worker disktype=ssd
kubectl get nodes --show-labels
kubectl get nodes -l disktype=ssd

After applying the pod, confirm where it landed and inspect events to explain any Pending state.

kubectl apply -f postgres.yaml
kubectl get pod postgres -o wide       # which node did it land on?
kubectl describe pod postgres          # events explain Pending if no match

Side by side, nodeAffinity is the more expressive successor to the simple nodeSelector map.

To truly dedicate a node, pair taints/tolerations with node affinity so only your pod can land there and it is forced to do so.

   Taint node (repel everyone) + Toleration (let my pod in) +
   Node Affinity (force my pod TO that node) = truly dedicated node.

A pod that must run on SSD nodes (hard rule) and prefers zone us-east-1a (soft rule). It stays Pending if no SSD node exists.

Graph legend — pinning a real Postgres pod to SSD, preferring a zone:

Affinity pulls a pod toward labeled nodes: hard required rules filter first, then soft preferred rules rank the survivors.

Graph legend — hard rules filter, then soft rules rank for Postgres:

• Node affinity = pod chooses nodes by labels, richer than nodeSelector.
• required = hard (Pending if unmet); preferred = soft (best-effort).
• Combine taints/tolerations + affinity to dedicate nodes properly.

• [ ] Labeled nodes and used a required nodeAffinity rule
• [ ] Saw a pod go Pending when no node matched
• [ ] Used a preferred rule with a weight
• [ ] Compared nodeSelector vs nodeAffinity