A highly available application is not one with many copies, but one whose copies do not fail together.

Suppose you run six copies of a web service and Kubernetes places five of them on one machine. On paper you have six replicas, but in practice you have one point of failure. If that machine loses power, needs a kernel update, or runs out of memory, five sixths of your capacity vanishes in a moment. The remaining copy is suddenly asked to handle six times its normal load, and it often collapses too.

The same problem exists at a larger scale. Cloud providers divide a region into zones, which are separate data-centre buildings with independent power and networking. If all your copies sit in one zone, a zone outage takes you offline even though you paid for many replicas. The scheduler does not know your application needs protection from these events unless you tell it, and topology spread constraints are the modern, precise way to say so.

What the default scheduler does on its own

Out of the box, the scheduler tries to balance resource use, and it has some mild tendency to spread pods of the same group. However, it optimises for many goals at once, such as filling nodes efficiently and keeping free capacity balanced. That mild tendency gives no guarantee. A busy cluster, a new node with lots of free room, or an uneven set of node sizes can easily cause bunching, where many copies land close together.

The scheduler filters nodes, scores the survivors, and spread constraints take part in both steps.

When a new pod needs a home, the scheduler first filters out nodes that cannot run it, for example because they lack free resources or do not match required rules. It then scores the remaining nodes and picks the best. Topology spread constraints influence both stages, depending on how strict you make them. A strict constraint removes nodes during filtering. A relaxed constraint only adds or removes points during scoring.

flowchart TD
    A[New pod arrives] --> B[Filter: resources, affinity, taints]
    B --> C[Filter: strict spread constraints
remove nodes that would exceed the allowed skew]
    C --> D{Any node left?}
    D -->|No| E[Pod stays Pending]
    D -->|Yes| F[Score: resource balance and other signals]
    F --> G[Score: relaxed spread constraints
favour domains that reduce imbalance]
    G --> H[Best node chosen and pod bound]
        

Decisions are made one pod at a time

The scheduler places pods individually, looking at the cluster as it exists at that moment. It does not plan a perfect layout for all six replicas in advance. Each new pod is placed so that the balance rule is respected given the pods already running. This one-at-a-time nature is important for understanding later behaviours, such as why balance can drift after pods are removed.

Everything in this feature reduces to counting pods in groups and comparing the counts.

A worked example with three zones

Imagine three zones named A, B, and C, and a service whose pods should be spread with a maximum skew of one. Right now zone A holds two pods, and zones B and C hold one pod each. The smallest count is one. The skew for zone A is two minus one, which is one. The skew for B and C is zero. Everything is within the limit, so the layout is acceptable.

Now a new pod arrives. If it lands in zone A, that zone would hold three pods, and its skew would become three minus one, which is two. That exceeds the limit, so zone A is not allowed. If it lands in zone B, that zone would hold two, the minimum stays at one, and the skew is one, which is fine. The scheduler therefore picks zone B or zone C. Following this simple rule, the pods naturally end up as evenly spread as the numbers allow.

graph TD
    subgraph Before
        A1[Zone A
2 pods
skew 1]
        B1[Zone B
1 pod
skew 0]
        C1[Zone C
1 pod
skew 0]
    end
    subgraph Options for the next pod
        A2[Zone A would be 3
skew 2
rejected]
        B2[Zone B would be 2
skew 1
allowed]
        C2[Zone C would be 2
skew 1
allowed]
    end
    A1 --> A2
    B1 --> B2
    C1 --> C2
        

A handful of settings describe a complete rule.

A topology spread constraint lives in the pod specification, and a pod can have several of them. Each constraint is built from a small set of fields. Some are required, and others are optional refinements added in newer Kubernetes versions. Understanding the purpose of each field first makes the deeper chapters easier to follow.

In the next chapters we take each field in turn, starting with the most important, maxSkew.

A single number that balances strictness against flexibility.

The maxSkew field must be a whole number greater than zero. A value of one is the tightest possible: no domain may hold more than one pod above the emptiest domain. A larger value permits more imbalance. Choosing it well is a tradeoff between evenness and the freedom of the scheduler to place pods where they fit.

How maxSkew behaves in each mode

When the constraint is strict, maxSkew is a hard limit: any placement that would push a domain past the limit is refused. When the constraint is relaxed, maxSkew is used as guidance: domains that would exceed it are scored lower, but they remain possible. This distinction explains why teams can use a tight maxSkew for a relaxed rule and still never see stuck pods.

The field that decides whether a constraint is a hard rule or a friendly hint.

flowchart TD
    A[Pod needs a node] --> B{Constraint mode}
    B -->|DoNotSchedule| C[Remove nodes that break maxSkew]
    C --> D{Any node left?}
    D -->|Yes| E[Schedule normally]
    D -->|No| F[Pod stays Pending]
    B -->|ScheduleAnyway| G[Keep all nodes
score better balance higher]
    G --> H[Pod always gets scheduled]
        

Which one should you choose?

Use DoNotSchedule when spreading is a correctness or safety requirement, for example when losing one zone must never remove more than a third of capacity. Use ScheduleAnyway when spreading is a quality improvement that must not compromise availability, for example in a cluster that autoscales and sometimes has only a few nodes. Many mature teams combine both: a strict rule at the zone level for the major protection and a relaxed rule at the host level for tidiness.

The label you name decides which failures your spreading protects against.

The topologyKey is the name of a node label. Nodes that carry the same value for that label are grouped into one domain. Pick the host name label, and every node is its own domain, so you spread across machines. Pick the zone label, and every zone is a domain, so you spread across data-centre buildings. Pick the region label, and you spread across geographic regions. The key defines the size of the failure you want to survive.

What happens to nodes without the label

Only nodes that carry the topologyKey label take part. A node that lacks the label is skipped when domains are counted and cannot be chosen by a constraint that uses that key. If some nodes are missing the label by accident, they silently fall out of the calculation, and your layout may not be as even as you believe. Always check that every relevant node has the label.

graph TD
    subgraph Zone A
        N1[node-1] 
        N2[node-2]
    end
    subgraph Zone B
        N3[node-3]
    end
    subgraph Zone C
        N4[node-4]
        N5[node-5]
        N6[node-6]
    end
    Z[Key zone gives 3 domains
A has 2 nodes, B has 1, C has 3]
    H[Key host name gives 6 domains
one per node]
        

A constraint only balances the pods you tell it to look at.

The labelSelector picks which existing pods count towards the balance. Almost always you select the pods of the same application, so that the copies of that application are spread among themselves. Only pods in the same namespace as the incoming pod are considered. Pods in other namespaces are invisible to the calculation, even if they carry the same labels.

The rolling update problem and matchLabelKeys

During a rolling update, old and new versions of the pods exist together. If the selector matches both, the scheduler counts them as one group. That sounds harmless, but it can produce a poor layout: the new version might end up concentrated in one zone because the old version fills the others. When the rollout completes and the old pods disappear, the new pods are left unbalanced.

The optional matchLabelKeys field solves this. You list label keys, and the scheduler reads their values from the incoming pod and adds them to the selector. By listing the label that identifies the revision of a Deployment, each version is balanced on its own. The result is that the final set of new pods is properly spread, independent of what the old pods looked like.

sequenceDiagram
    participant D as Deployment rollout
    participant S as Scheduler
    participant Z as Zones A B C
    D->>S: Create pod of new revision
    S->>Z: Count only pods with the same revision label
    Z-->>S: New revision counts per zone
    S->>S: Apply maxSkew to new revision counts
    S->>Z: Place pod in the least loaded zone for this revision
    Note over Z: Old revision pods do not distort the new layout
        

Encouraging the cluster to grow into the shape you want.

Suppose you want your pods spread across at least three zones, but your cluster currently has nodes in only two. With a plain constraint, the scheduler sees two domains, balances between them, and everything looks fine. You have quietly lost the third-zone protection you wanted. The minDomains field lets you state the minimum number of domains you expect to exist.

When the number of eligible domains is lower than minDomains, the scheduler treats the global minimum count as zero. That makes the skew of any domain that already holds pods large enough to block further placement in strict mode. Pods stay Pending, and if a cluster autoscaler is running, those Pending pods signal that a new node in a new zone would help. This field only works together with the strict mode.

Two settings decide whether nodes the pod cannot use still take part in the balance.

Not every node in a cluster is a valid home for a given pod. Some are excluded by the pod’s node selector or node affinity, and some are tainted so the pod is not welcome. A subtle question arises: should such nodes and their domains be counted when calculating the minimum and the skew? Two optional fields answer this.

The tainted-zone surprise

Consider a zone where every node is tainted for a special workload, and your pod does not tolerate that taint. With the default taints policy, that zone still counts as a domain with zero pods. The global minimum is therefore zero forever, because your pod can never go there. In strict mode this can stop the other zones from growing beyond the allowed skew, and pods stay Pending even though plenty of usable capacity exists elsewhere. Setting nodeTaintsPolicy to Honor removes such unusable domains from the count and cures the problem.

Several rules can apply to one pod at the same time, and Kubernetes provides sensible defaults.

A pod may carry more than one topology spread constraint, for example one for zones and one for host names. The scheduler treats them together with a logical AND: a node must satisfy every strict constraint to remain a candidate. Relaxed constraints each add to the scoring. This combination is the standard pattern for protecting against both zone failures and machine failures at once.

flowchart TD
    P[Incoming pod] --> C1[Constraint 1
zone, maxSkew 1, DoNotSchedule]
    P --> C2[Constraint 2
host name, maxSkew 1, ScheduleAnyway]
    C1 --> F[Nodes in zones that keep zone skew within 1]
    C2 --> S[Score nodes that keep host skew low]
    F --> W[Candidate nodes]
    S --> W
    W --> B[Best scoring candidate wins]
        

Cluster-level default constraints

If a pod defines no spread constraints of its own, and it belongs to a Service, ReplicaSet, StatefulSet, or similar group, the scheduler applies built-in default constraints. These are relaxed rules: one across host names with a maximum skew of three, and one across zones with a maximum skew of five. They give a gentle nudge toward spreading without ever blocking a pod. Cluster administrators can replace these defaults with their own through the scheduler configuration.

Choosing between spreading, anti-affinity, affinity, and taints.

Kubernetes offers several tools that influence placement. Spread constraints overlap most with pod anti-affinity, since both can be used to keep replicas apart. The difference is in the promise they make. Anti-affinity says “not together with these pods.” Spread constraints say “keep the counts in each domain close to each other.” That difference in wording has large practical consequences.

Everyday situations where a spreading rule pays for itself.

Balance is created at placement time, and real events can disturb it afterwards.

Rolling updates

During a rolling update, surge pods must satisfy strict constraints just like any other pod. If a zone is full and the constraint blocks other zones from getting further ahead, the surge pod waits, and the rollout pauses. Using matchLabelKeys with the revision label keeps each version balanced separately, and leaving a little spare capacity in every zone keeps rollouts moving smoothly.

Scaling down

When you reduce the number of replicas, the controller chooses which pods to delete. It has its own ordering rules, and they do not guarantee that the remaining pods stay balanced across domains. A scale-down from nine to six may leave you with a layout such as three, three, zero instead of two, two, two. The constraint will only matter again when new pods are placed.

Node and zone failures

When a node fails, its pods are recreated and each new pod is placed according to the constraints. If a whole zone is down and the constraint is strict with a small maxSkew, replacement pods may be blocked from piling into the surviving zones, and they wait until the zone recovers. This is exactly the behaviour some teams want for stability, and exactly what other teams must avoid by choosing a relaxed mode or a larger maxSkew.

sequenceDiagram
    participant Z as Zone C
    participant K as Controller
    participant S as Scheduler
    participant A as Zones A and B
    Z-->>K: Zone C goes down, pods lost
    K->>S: Create replacement pods
    S->>A: Check skew with zone C counted as a domain with zero
    alt Strict mode and small maxSkew
        S-->>K: Replacement pods stay Pending
    else Relaxed mode or larger maxSkew
        S->>A: Place replacement pods in zones A and B
    end
        

Spread constraints are cheaper than anti-affinity but not free.

For each pod, the scheduler must count matching pods per domain and simulate the effect of every candidate placement. Constraints on the host name label create as many domains as there are nodes, which means more counting in very large clusters. Constraints on zones create only a handful of domains and are inexpensive. Broad selectors that match many pods increase the counting work too.

Placement rules affect capacity, and capacity is shared.

Topology spread constraints are not a security boundary, but they do interact with security and fairness in a shared cluster. Because the rules live in the pod specification, anyone who can create pods can write them. In a multi-tenant cluster, misuse can waste capacity or block other teams’ workloads, and node labels that feed the rules deserve protection.

Most spread problems show up as Pending pods or a layout that looks lopsided.

When a strict constraint cannot be satisfied, the scheduler records an event on the pod saying that a number of nodes did not match the pod topology spread constraints. That message is your starting point. Combined with a view of how many matching pods run in each domain, it usually reveals the cause within minutes.

Proven combinations you can adapt to your own services.

Habits that lead to stuck pods, false confidence, and confusing layouts.

A compact checklist for safe and predictable spreading.

How teams apply spread constraints in production.

Skew is the number of matching pods in a domain minus the smallest number of matching pods in any eligible domain. The scheduler makes sure this difference stays within maxSkew.

DoNotSchedule is strict: nodes that would exceed maxSkew are removed, and the pod may stay Pending. ScheduleAnyway is relaxed: the pod is always scheduled, but placements that reduce imbalance score higher.

Yes. Unlike required pod anti-affinity, spread constraints simply keep the counts in each zone close together, so extra replicas double up evenly.

No. The rules apply only when a pod is scheduled. A separate descheduler component can evict pods that violate constraints so that they are placed again.

No. Only matching pods in the same namespace as the incoming pod are counted.

They are ignored by that constraint. They are not counted as a domain and cannot be selected for a pod that uses that key, so make sure the label is present on every relevant node.

A strict constraint left no node that keeps the skew within the limit. Common causes are a full or small zone, a tainted domain counted as empty, a high minDomains value, or a selector that counts more pods than expected.

It sets the minimum number of eligible domains you expect. If fewer exist, the baseline count is treated as zero, so strict mode blocks pods beyond the allowed skew and signals that capacity in a new domain is needed.

Surge pods must satisfy strict rules like any other pod. If the selector matches both old and new versions, the new version may end up unbalanced. Using matchLabelKeys with the revision label balances each version independently.

Yes. For pods that belong to a Service or similar controller and define no constraints, the scheduler applies relaxed defaults across host names and zones. They give a gentle nudge and never block scheduling.

For balancing replicas of one application, spread constraints are usually simpler, cheaper, and more flexible. Use anti-affinity to keep two specific workloads apart or to demand strictly one pod per domain.

No. It limits the difference between domains. Each domain can hold many pods as long as the domains stay within the allowed difference of each other.

Topology spread constraints let you describe how evenly copies of an application should be distributed across nodes, zones, regions, or any other grouping you define with node labels. The scheduler measures balance with skew, the difference between a domain and the emptiest eligible domain, and keeps it within your maxSkew. Whether the rule blocks placement or only guides it is decided by the whenUnsatisfiable setting.

The feature is powerful because it is flexible, but its behaviour depends on details: which pods are counted, which nodes count as domains, how tainted or excluded nodes are treated, and when the rules are applied. Balance is created at placement time and can drift afterwards, so monitoring and occasional correction matter. Used with care, spreading turns a pile of replicas into a truly resilient service.