Course contentsShow
← Cloud and Infrastructure
Lesson 1359 of 2,98927. Kubernetes Scheduling and ResourcesFree lesson

Affinity Troubleshooting

Debug common affinity issues: pending pods, unschedulable states, and conflicting rules.

Affinity Troubleshooting

You'll learn: How to diagnose and resolve common affinity issues that leave pods pending or unschedulable.

When you've configured node affinity, pod affinity, or anti-affinity rules, pods sometimes refuse to schedule—and the reasons aren't always obvious. Troubleshooting affinity problems means understanding why the scheduler can't find a suitable node.

Common Affinity Issues

Pending Pods with No Matching Nodes

The most frequent issue: your required node affinity or pod affinity rules are too restrictive. If you specify requiredDuringSchedulingIgnoredDuringExecution with labels that no node possesses, the pod stays pending indefinitely.

Check: Run kubectl describe pod <pod-name> and look for events like "0/5 nodes are available: 5 node(s) didn't match node selector" or "didn't match pod affinity rules."

Conflicting Rules

Sometimes your affinity and anti-affinity rules contradict each other. For example, requiring pods to be co-located (pod affinity) while also demanding they avoid each other (anti-affinity) creates an impossible situation.

Check: Review your affinity and anti-affinity configurations side-by-side. Ensure required rules don't cancel each other out.

Topology Key Mismatches

If your topology key (like kubernetes.io/hostname or topology.kubernetes.io/zone) doesn't exist on nodes or doesn't have the expected values, affinity rules fail silently.

Check: Verify nodes have the labels you're targeting: kubectl get nodes --show-labels

Taints Blocking Affinity Matches

Even when affinity rules match, node taints can still block scheduling unless your pod has matching tolerations.

Check: Look for "node(s) had taint" messages in pod events.

Quick Debug Workflow

  1. Describe the pending pod
  2. Check node labels match your selectors
  3. Verify topology keys exist
  4. Review for conflicting affinity/anti-affinity
  5. Check taints and tolerations

Key Takeaway: Affinity troubleshooting centers on verifying label matches, avoiding rule conflicts, and confirming topology keys exist—always start with kubectl describe pod to see scheduler rejection reasons.