preferredDuringSchedulingIgnoredDuringExecution — soft inter-pod affinity

preferredDuringSchedulingIgnoredDuringExecution is the soft variant of Pod affinity and anti-affinity. Instead of eliminating nodes that don’t satisfy, it adds weight to the score. If no node satisfies the preference, the Pod still schedules. This lesson covers the syntax, the weight semantics, and when to use preferred vs required.

The syntax

spec:
  affinity:
    podAffinity:
      preferredDuringSchedulingIgnoredDuringExecution:
      - weight: 80
        podAffinityTerm:
          topologyKey: kubernetes.io/hostname
          labelSelector:
            matchLabels:
              app: cache

flowchart LR
    A[Feasible nodes] --> B[Score phase]
    B --> C{Node has Pod<br/>matching selector?}
    C -->|yes| D["Score += weight"]
    C -->|no| E[Score unchanged]
    D --> F[Final score]
    E --> F

The weight

The weight (1-100) is added to the node’s score for nodes that satisfy the preference. A weight of 100 is a strong preference; a weight of 10 is weak.

flowchart TB
    A["Node X<br/>has cache Pod"] --> B["Score: 80"]
    A2["Node Y<br/>no cache Pod"] --> B2["Score: 0"]
    A3["Node Z<br/>has cache Pod"] --> B3["Score: 80"]
    A --> C[Other plugins]
    A2 --> C
    A3 --> C
    C --> D[Final score]

Pod anti-affinity preferred

spec:
  affinity:
    podAntiAffinity:
      preferredDuringSchedulingIgnoredDuringExecution:
      - weight: 100
        podAffinityTerm:
          topologyKey: kubernetes.io/hostname
          labelSelector:
            matchLabels:
            app: web

The Pod prefers to land on a node without an app: web Pod. If no such node exists, the Pod schedules anywhere with a low score.

Preferred vs required

flowchart TB
    A{Affinity type} -->|required| B["If no match: Pending"]
    A -->|preferred| C["If no match: schedule anywhere"]
    C --> D["Match: score += weight"]

Combining preferred and required

spec:
  affinity:
    podAntiAffinity:
      requiredDuringSchedulingIgnoredDuringExecution:
      - topologyKey: kubernetes.io/hostname
        labelSelector:
          matchLabels:
            app: web
      preferredDuringSchedulingIgnoredDuringExecution:
      - weight: 100
        podAffinityTerm:
          topologyKey: topology.kubernetes.io/zone
          labelSelector:
            matchLabels:
              app: web

The Pod must not co-locate with app: web on the same node (required). The Pod prefers a different zone from existing app: web Pods (preferred). The combination gives strict node separation and zone preference.

Production patterns

Pattern 1: prefer co-location with cache

affinity:
  podAffinity:
    preferredDuringSchedulingIgnoredDuringExecution:
    - weight: 80
      podAffinityTerm:
        topologyKey: kubernetes.io/hostname
        labelSelector:
          matchLabels:
            app: cache

The Pod prefers a node with cache. If no such node exists, the Pod schedules anywhere.

Pattern 2: prefer separation from web

affinity:
  podAntiAffinity:
    preferredDuringSchedulingIgnoredDuringExecution:
    - weight: 100
      podAffinityTerm:
        topologyKey: kubernetes.io/hostname
        labelSelector:
          matchLabels:
            app: web

The Pod prefers to be on a node without app: web. If all nodes have web Pods, the Pod schedules anyway.

Pattern 3: combine multiple preferences

affinity:
  podAffinity:
    preferredDuringSchedulingIgnoredDuringExecution:
    - weight: 50
      podAffinityTerm:
        topologyKey: kubernetes.io/hostname
        labelSelector:
          matchLabels:
            app: cache
  podAntiAffinity:
    preferredDuringSchedulingIgnoredDuringExecution:
    - weight: 100
      podAffinityTerm:
        topologyKey: kubernetes.io/hostname
        labelSelector:
          matchLabels:
            app: db

Prefer cache co-location (weight 50); prefer separation from db (weight 100). The db separation is stronger.

Failure modes

Failure 1: weight too low

preferredDuringSchedulingIgnoredDuringExecution:
- weight: 1
  podAffinityTerm:
    topologyKey: kubernetes.io/hostname
    labelSelector:
      matchLabels:
        app: cache

A weight of 1 is rarely significant in the total score; the scheduler’s other plugins dominate. The preference is effectively no-op.

The fix: increase the weight (50-100 is meaningful).

Failure 2: preference unsatisfiable

A preference that matches no Pod is silent. The Pod schedules anywhere. The fix: verify the cluster’s labels and Pods.

Failure 3: required mixed with preferred

# WRONG: required belongs in requiredDuringScheduling
preferredDuringSchedulingIgnoredDuringExecution:
- weight: 100
  podAffinityTerm:
    required: true   # not valid here
    topologyKey: kubernetes.io/hostname
    labelSelector:
      matchLabels:
        app: cache

The required field is for nodeSelectorTerms in required affinity. Preferred uses only weight and podAffinityTerm.

Quiz

Production discipline

• Use preferred for operational placement. Latency, performance, cost — anything that prefers but allows fallback.
• Use required for hard separation. A primary and replica that must not co-locate; a workload that must not share a node with another workload.
• Verify weights. A weight of 50-100 is meaningful; a weight of 1 is not.
• Combine preferred and required. A workload can have both: required for separation, preferred for performance.
• Audit the resulting distribution. A dashboard that surfaces per-node Pod counts catches preference failures.

Preferred Pod affinity is the right tool for soft placement. Operators who use it deliberately have workloads that land predictably with sensible fallbacks.