Mastering Kubernetes Pod and Node Affinity: Practical Guides and Real-World Examples

Pod Scheduling Affinity

In Kubernetes, pod affinity and anti‑affinity are advanced scheduling strategies that control how pods are placed relative to nodes or other pods, enabling topology constraints, resource locality, and high availability.

Overview

Affinity consists of two main types: node affinity and pod affinity.

Node Affinity

Node affinity is a core mechanism for directing pods to specific nodes, offering more flexibility than the traditional nodeSelector. It defines rules via the nodeAffinity field, which includes hard rules ( requiredDuringSchedulingIgnoredDuringExecution) and soft rules ( preferredDuringSchedulingIgnoredDuringExecution).

Hard Rule Matching

Pods are scheduled only to nodes that satisfy all required conditions; otherwise they remain pending.

# Label a node
kubectl label node node01 env=prod disk-type=ssd cpu-cores=3

# Deployment using hard node affinity
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-affinity
spec:
  replicas: 5
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      affinity:
        nodeAffinity:
          requiredDuringSchedulingIgnoredDuringExecution:
            nodeSelectorTerms:
            - matchExpressions:
              - key: env
                operator: In
                values: ["prod"]
              - key: disk-type
                operator: In
                values: ["ssd"]
              - key: cpu-cores
                operator: Gt
                values: ["2"]
      containers:
      - name: nginx
        image: nginx

After applying the manifest, all pods are scheduled to node01. If a required label is removed, the pods become Pending because they no longer match the hard rules.

Soft Rule Matching

Soft rules assign scores to nodes that meet the criteria; the scheduler prefers nodes with higher scores but will fall back to other nodes if necessary.

# Deployment using soft node affinity
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-affinity
spec:
  replicas: 10
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      affinity:
        nodeAffinity:
          preferredDuringSchedulingIgnoredDuringExecution:
          - weight: 100
            preference:
              matchExpressions:
              - key: region
                operator: In
                values: ["east"]
          - weight: 70
            preference:
              matchExpressions:
              - key: disk-type
                operator: In
                values: ["ssd"]
      containers:
      - name: nginx
        image: nginx

When both node01 (region=east) and node02 (disk-type=ssd) are labeled, the scheduler places more pods on node01 because it has a higher weight.

Mixed Hard and Soft Rules

# Mixed hard and soft node affinity example
apiVersion: v1
kind: Pod
metadata:
  name: mixed-affinity-pod
spec:
  affinity:
    nodeAffinity:
      requiredDuringSchedulingIgnoredDuringExecution:
        nodeSelectorTerms:
        - matchExpressions:
          - key: env
            operator: In
            values: ["prod"]
      preferredDuringSchedulingIgnoredDuringExecution:
      - weight: 80
        preference:
          matchExpressions:
          - key: gpu
            operator: Exists
  containers:
  - name: nginx
    image: nginx

Pod Affinity

Pod affinity controls pod placement based on the location of other pods, allowing pods to be co‑located on the same node, zone, or other topology domain.

Classification

Inter‑pod affinity (pods are attracted to each other)

Pod anti‑affinity (pods are repelled from each other)

Hard Rule Example

# Deployment with hard pod affinity
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-affinity
spec:
  replicas: 10
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      affinity:
        podAffinity:
          requiredDuringSchedulingIgnoredDuringExecution:
          - labelSelector:
              matchExpressions:
              - key: app
                operator: In
                values: ["nginx"]
            topologyKey: "kubernetes.io/hostname"
      containers:
      - name: nginx
        image: nginx

All pods are scheduled onto the same node because they satisfy the required pod affinity rule.

Soft Rule Example (rarely used in production)

Soft pod affinity uses preferredDuringSchedulingIgnoredDuringExecution to express a preference without strict enforcement.

Pod Anti‑Affinity

Pod anti‑affinity ensures that pods are not placed together in the same topology domain, improving high availability and resource isolation.

Hard Rule Example

# Deployment with hard pod anti‑affinity
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-affinity
spec:
  replicas: 10
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      affinity:
        podAntiAffinity:
          requiredDuringSchedulingIgnoredDuringExecution:
          - labelSelector:
              matchExpressions:
              - key: app
                operator: In
                values: ["nginx"]
            topologyKey: "kubernetes.io/hostname"
      containers:
      - name: nginx
        image: nginx

Only one pod per node can run; additional pods remain Pending because the anti‑affinity rule cannot be satisfied.

Pod Anti‑Affinity vs. DaemonSet

Feature

Pod Anti‑Affinity

DaemonSet

Definition

Scheduling policy that controls where pods are placed

Controller that ensures one pod replica runs on each node

Purpose

High availability, resource isolation, performance optimization

Run cluster‑level daemons such as log collectors or monitoring agents

Scheduling Mechanism

Scheduler evaluates labelSelector and topologyKey DaemonSet controller automatically creates a pod on every node

Configuration

Defined in spec.affinity.podAntiAffinity of a pod spec

Defined via a DaemonSet resource object

Use Cases

Distribute replicas across nodes or zones for HA

Run a single instance of a service on each node

Pod Count

Determined by replica count and scheduling constraints

One pod per node, matching the number of nodes

Node affinity allows fine‑grained control of pod placement; if the specified labels do not match, pods stay in Pending state.

Pod anti‑affinity ensures that only one pod with the same label runs per topology domain; excess pods remain pending.