Topology Spread Constraints

## The problem A Deployment with six replicas is not highly available if the scheduler bin-packs all six onto two nodes in one availability zone. The default scheduler already spreads a little — its `PodTopologySpread` plugin contributes score, and by default the cluster ships soft constraints on zone and hostname — but nothing guarantees a distribution. `topologySpreadConstraints` is the explicit, declarative way to state "these pods must be spread across these domains, this evenly". ## Domains A *topology domain* is the set of nodes that share the same value for a given node label. Choose the label with `topologyKey`: - `topology.kubernetes.io/zone` — one domain per availability zone; protects against a zone outage. - `kubernetes.io/hostname` — one domain per node; protects against a single-node failure and stops bin-packing. - Any custom label — `rack`, `topology.kubernetes.io/region`, `nodepool`. Nodes that do not carry the label at all are **not** a domain; they are excluded from the calculation entirely, and pods on them are invisible to it. That is a common source of surprise on clusters with mixed or unlabelled nodes. ## The skew calculation For a given constraint the scheduler counts, in each eligible domain, the pods matching `labelSelector`. Then: `skew = pods in the domain being considered − minimum pod count across eligible domains` A candidate placement is feasible only if the resulting skew stays ≤ `maxSkew`. In effect the scheduler must place the next pod in one of the currently-emptiest domains once the spread reaches the limit. Worked example: 3 zones, `maxSkew: 1`, and current counts A=2, B=1, C=1. Minimum is 1. Placing in A gives 3 − 1 = 2 > 1, infeasible. Placing in B gives 2 − 1 = 1, fine. So the 5th replica goes to B or C. Six replicas across three zones land 2/2/2; seven land 3/2/2, which is the best arithmetic allows. `maxSkew` must be at least 1. Larger values loosen the requirement: `maxSkew: 2` over three zones permits 4/2/2, which is often the pragmatic choice when zones have unequal capacity. ## labelSelector counts more than you think The selector is evaluated against **all pods in the namespace**, not just the ones created by this controller. If two Deployments share the label `app: web`, a constraint selecting `app: web` balances their combined population. That is sometimes exactly what you want (all frontends spread together) and sometimes a bug (a canary Deployment perturbing the stable one's placement). Select precisely; where you want per-revision balance, `matchLabelKeys: [pod-template-hash]` makes the scheduler add the current revision's hash to the selector automatically so old and new ReplicaSets are counted separately during a rollout. ## whenUnsatisfiable `DoNotSchedule` makes the constraint a hard filter: if no domain can take the pod without breaking `maxSkew`, the pod stays `Pending` with an event naming the constraint. `ScheduleAnyway` makes it a scoring preference: the scheduler prefers balanced placements but never refuses to place the pod. See the dedicated comparison for how to choose. ## Related knobs - **`minDomains`** (with `DoNotSchedule`) — asserts a minimum number of eligible domains; if fewer exist, the global minimum is treated as zero, which forces the scheduler to keep domains free rather than piling into the few that exist. Useful with cluster autoscaling so new zones get provisioned. - **`nodeAffinityPolicy` / `nodeTaintsPolicy`** — whether nodes excluded by the pod's own nodeSelector/affinity or by untolerated taints are counted when computing domains. Defaults are `Honor` for affinity and `Ignore` for taints. ## Cluster-wide defaults If a pod declares no constraints, the scheduler applies default constraints from its configuration. The shipped defaults are soft (`ScheduleAnyway`) with `maxSkew: 3` on both zone and hostname — enough to nudge spreading, nowhere near a guarantee. Administrators can replace them in the `KubeSchedulerConfiguration` for the `PodTopologySpread` plugin. ## Verifying `kubectl get pods -o wide` shows nodes; joining pods to node zone labels shows the actual zone distribution. When a pod is Pending, `kubectl describe pod` prints something like `didn't match pod topology spread constraints`, which tells you the constraint, not the resource, is the blocker.