Add node affinity and pod scheduling guide

Pod Scheduling and Node Affinity

By default, the Kubernetes scheduler places pods on any node with sufficient resources. Use affinity rules and taints to control placement.

Node Affinity

Use node affinity to attract pods to specific nodes:

affinity:
  nodeAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
      nodeSelectorTerms:
        - matchExpressions:
            - key: topology.kubernetes.io/zone
              operator: In
              values:
                - us-east-1a
                - us-east-1b

Taints and Tolerations

Taints repel pods from nodes. Add a toleration to allow specific pods onto tainted nodes:

tolerations:
  - key: "gpu"
    operator: "Equal"
    value: "true"
    effect: "NoSchedule"

Common Patterns

• Zone spreading: Use pod anti-affinity to spread replicas across availability zones
• GPU isolation: Taint GPU nodes, only ML workloads tolerate the taint
• Dedicated nodes: Taint nodes for specific teams, add tolerations to their deployments

Troubleshooting

If a pod is stuck in Pending, check kubectl describe pod for scheduling errors. Common causes:

• No nodes match the affinity rules
• All matching nodes are tainted and the pod lacks tolerations
• Insufficient resources on matching nodes