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
- Describe the pending pod
- Check node labels match your selectors
- Verify topology keys exist
- Review for conflicting affinity/anti-affinity
- 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.