Topology Spread Constraints

Scheduling and Placement / Guide 42 of 103 / Advanced

• Kubernetes1.36.4
• Cluster4 nodes
• Runtimecontainerd 2.2.6
• CNICalico v3.32.1
• TimeAbout 35 min

nodeTaintsPolicy needs 1.26 or newer. On older clusters the workaround is a nodeSelector.

This guide includes

Use this when replicas need to spread evenly and half of them stay Pending instead. This matters because the control plane counts as a topology domain, so a constraint that looks obviously correct can turn out to be impossible to satisfy.

• asking for even distribution with maxSkew: 1 and watching three replicas never start
• reading the scheduler's own explanation out of the Pod condition
• finding that the answer is the control plane's taint, counted as a domain
• setting nodeTaintsPolicy: Honor and watching all nine schedule
• switching to whenUnsatisfiable: ScheduleAnyway to turn the constraint into a preference

Before you start

• The labels and nodeSelector guide, and the node affinity guide.
• The taints and tolerations guide. The control plane's taint is the cause of this guide's central surprise.
• The Pod stuck Pending guide, for reading the scheduler's tally.

1. 1

   Six replicas, maxSkew 1, and three that never start

2. 2

   The scheduler explains it, and the answer is the control plane

3. 3

   nodeTaintsPolicy: Honor, and all nine schedule

4. 4

   ScheduleAnyway, and what the scheduler does unaided

Official sources

• Pod topology spread constraints
• nodeAffinityPolicy and nodeTaintsPolicy
• Well-known labels and annotations
• Assigning Pods to Nodes
• kube-scheduler