Last reviewed: November 13, 2026 (Asia/Shanghai); official Kubernetes references retrieved November 12 UTC.
Direct answer
Review a Kubernetes topology spread patch by identifying the Pods it counts, deriving the eligible topology domains, and calculating where one incoming Pod can be placed. Check the rendered selector against the incoming Pod’s own labels, distinguish DoNotSchedule from ScheduleAnyway, and test the calculation against actual node labels and scheduler evidence. A balanced replica count in one screenshot does not establish that the rule will behave correctly during a rollout or a loss of eligible domains.
The Pod Topology Spread Constraints guide explains the scheduling model and its limitations. The Pod API reference defines the fields, while Labels and Selectors explains how the counted group is selected. Together they support a review that connects the manifest to a specific placement decision.
Who this is for
Use this workflow when a coding agent changes spec.topologySpreadConstraints in a Pod or controller template, or edits chart values and overlays that render it. It also applies when a nearby label change alters the Pods counted by an existing constraint. The examples assume the standard Kubernetes scheduler with topology spreading enabled.
Give the agent the target Kubernetes version, scheduler profile, approved node pools, topology labels, supported replica range, and availability requirement. Ask for a rendered before-and-after template and an explanation of each changed counting rule. The examples below are illustrative review fixtures and proposed acceptance checks. No authenticated cluster test or deployment was performed for this article.
Key takeaways
- A topology domain is a node-label key/value pair, such as one value of
topology.kubernetes.io/zone. - Spread selectors count matching Pods in the incoming Pod’s namespace; controller ownership is not an implicit selector.
- The incoming Pod should match its own spread selector so its placement contributes to the calculation.
- With
DoNotSchedule, calculate the target domain’s count after placement against the documented global minimum. minDomainschanges that minimum to zero when too few eligible domains exist; it does not create missing capacity.- Inclusion policies change spread accounting. Other scheduling requirements still apply.
- Scheduling new Pods does not guarantee that existing Pods will be rebalanced after removal or scale-down.
Sources checked
Three primary Kubernetes references were retrieved successfully on November 12, 2026 UTC:
- Pod Topology Spread Constraints
documents skew, domain eligibility,
minDomains, selector matching, inclusion policies, revision-specific grouping, combined constraints, and known limitations. It displays an October 27, 2025 modification date. - Pod v1 core API reference
defines
TopologySpreadConstraint, including required fields, the global-minimum calculation, policy defaults, andmatchLabelKeys. It displays an August 26, 2026 update for Kubernetes v1.37. - Labels and Selectors documents label grouping, equality and set requirements, and the conjunction of selector requirements. It displays a March 15, 2026 modification date.
These maintained platform references support an evergreen review task. Their retrieval dates establish when the documentation was checked, rather than when the behavior was introduced. Match fields and feature availability to the target cluster; current documentation does not establish its scheduler configuration.
Contract details to verify
Resolve the counted group before reviewing the numbers
Render every affected environment from the candidate revision. Compare the complete Pod labels and spread constraints with the current version. Record the namespace, workload selector, spread selector, topology keys, and any admission or controller changes visible on an admitted Pod.
The spread selector groups Pods by labels within the namespace. It does not automatically restrict the group to one Deployment UID. Two workloads sharing the selected labels can affect each other’s counts; old and new revisions can also belong to the same group. Use the label-selector reference
to evaluate every requirement: matchLabels and matchExpressions are combined with AND semantics. Labels organize objects but do not guarantee uniqueness.
Check the incoming Pod itself. A selector typo can exclude it from the group it is meant to balance. The spread guide calls these uncounted members “ghost pods”: they can accumulate without changing the expected count. Compare the selector with the rendered template and with the admitted Pod labels. A successful placement alone cannot catch this mistake.
For example, this fragment belongs inside a Deployment’s spec.template, alongside its existing container configuration:
metadata:
labels:
app.kubernetes.io/name: queue-api
app.kubernetes.io/instance: spread-review
spec:
topologySpreadConstraints:
- maxSkew: 1
topologyKey: topology.kubernetes.io/zone
whenUnsatisfiable: DoNotSchedule
nodeAffinityPolicy: Honor
nodeTaintsPolicy: Honor
labelSelector:
matchLabels:
app.kubernetes.io/name: queue-api
app.kubernetes.io/instance: spread-review
The labels and policy are illustrative. Both inclusion-policy fields are stable in Kubernetes 1.33 and later. Check older targets against their versioned API and feature configuration. This fragment deliberately uses nodeTaintsPolicy: Honor; omitting that field has Ignore behavior, so adding it to an existing workload is a counting-policy change to review.
Derive domains from the actual node inventory
Nodes with the same value for the chosen topologyKey belong to the same domain. List the actual node labels and confirm that the chosen key represents the intended failure boundary. Spreading across hostnames does not establish zone diversity. The guide recommends well-known zone and region labels rather than assuming that a private label has the same meaning in every environment.
For DoNotSchedule constraints, nodes missing a required topology key are bypassed; their Pods do not supply the expected counts, and they cannot serve as placement targets for that constraint. Check label coverage before treating a zone as empty. With several constraints, inspect all required topology keys.
Review domain inclusion separately from node schedulability. nodeAffinityPolicy: Honor accounts for the incoming Pod’s node selector and affinity; its omitted value behaves as Honor. nodeTaintsPolicy: Honor accounts for taints and the incoming Pod’s tolerations; its omitted value behaves as Ignore. An Ignore policy does not authorize a Pod to violate its actual affinity or taint restrictions. It changes the nodes considered for spread calculations.
Use the node-affinity review guide to resolve required placement rules, and the taints and tolerations review guide to inspect excluded pools. A domain included in spread accounting can still lack usable resources or otherwise schedulable nodes.
Calculate one placement using the global minimum
For DoNotSchedule, maxSkew limits the difference between the target domain’s matching-Pod count and the global minimum. It must be greater than zero. For an incoming Pod that matches its selector, add one to the target count before comparing. Derive the global minimum using the constraint’s eligible domains and minDomains rule.
Suppose three eligible zones contain (2, 2, 1) matching Pods, maxSkew is one, and minDomains is omitted. The global minimum is one. Holding other scheduling conditions constant gives this calculation:
| Candidate domain | Count after placement | Target count minus global minimum | Spread decision |
|---|---|---|---|
| Zone A | 3 | 3 − 1 = 2 | Reject this domain |
| Zone B | 3 | 3 − 1 = 2 | Reject this domain |
| Zone C | 2 | 2 − 1 = 1 | Allow this domain |
This permits a node in zone C; it does not identify a particular node or reserve resources there. The API reference also shows that an already imbalanced distribution can accept an incoming Pod in a less populated domain without repairing the entire distribution. Review the incoming placement calculation rather than requiring every existing pair of domain counts to satisfy a new global balance assertion.
ScheduleAnyway makes spreading a scoring preference. Other scheduler priorities can affect the result, and other hard constraints can still prevent scheduling. Do not require a soft constraint to produce the same refusal behavior as DoNotSchedule.
Decide what fewer eligible domains should mean
minDomains is allowed only with DoNotSchedule and must be positive when supplied. When it is omitted, the constraint behaves as though it were one. When fewer eligible domains exist than the configured minimum, the spread calculation uses a global minimum of zero.
Consider two eligible zones with one matching Pod each, maxSkew: 1, and minDomains: 3. Adding another matching Pod to either zone gives 2 − 0 = 2, so this spread rule rejects both targets. Omitting minDomains in the same two-zone fixture gives a minimum of one and permits the addition under this rule. The two configurations express different responses to reduced domain availability.
Choose that response with the workload owner. A strict minimum can leave replacement Pods Pending while preserving the chosen spread restriction. It does not create another zone, prove an availability floor, or relocate existing replicas. The guide also notes that topology domains are discovered from existing nodes: a node pool scaled to zero may be absent from the scheduler’s domain inventory. Verify the autoscaler’s documented topology awareness separately before relying on it to recover the missing domain.
Check combined constraints and rollout grouping
When multiple hard spread constraints apply, the selected node must satisfy all of them. A zone rule may permit only zone B while a hostname rule permits only a node in zone A. Each rule can appear reasonable alone while their intersection is empty. Calculate the intersection from the same node and Pod snapshot before proposing a larger skew or a soft rule.
If the patch adds matchLabelKeys, identify how it changes the counted group. The documented pod-template-hash example separates Deployment revisions. Without that revision condition, matching old and new replicas can contribute to the same group. Neither choice automatically meets the owner’s availability requirement; compare the intended group during both steady state and overlap.
The API requires a selector when matchLabelKeys is used, forbids repeating the same key in both fields, and ignores listed keys missing from the incoming Pod. The field depends on feature configuration, and the concept guide warns against using label values that are edited directly on existing Pods. Verify the effective selector and feature behavior on the target version. If a rollout changes grouping, include the Deployment rollout review
so surge capacity and available replicas receive their own checks.
Retain evidence for both placement and refusal
Use an approved disposable cluster with representative node labels, scheduler settings, and enough capacity to isolate the rule. Let the scheduler assign the incoming fixture. Establish the initial matching-Pod counts, then introduce one candidate Pod at a time. These read-only captures use illustrative names; replace them with the actual fixture identities:
kubectl --context review-cluster get nodes -o json > review-nodes.json
kubectl --context review-cluster --namespace agent-review \
get pods -o json > review-pods.json
kubectl --context review-cluster --namespace agent-review \
get pod spread-check -o json > review-incoming.json
kubectl --context review-cluster --namespace agent-review \
describe pod spread-check
Check each command’s exit status before using saved output. Join assigned Pod node names to the node-label snapshot, then derive the domain counts using the actual selector. Keep zero-Pod eligible domains in the table. Preserve the incoming Pod UID, labels, effective constraints, owner references, assigned node or PodScheduled condition, and scheduler events with timestamps. A namespace-wide snapshot helps expose other matching workloads and selector mismatches that a narrow list could hide.
Run the relevant proposed cases, restoring the baseline between them:
| Controlled case | Evidence to require |
|---|---|
Three-zone (2, 2, 1) baseline with one matching incoming Pod | New placement is in zone C; node and Pod snapshots support the arithmetic |
| Incoming Pod does not match its own selector | Inspection detects the mismatch and excluded count, even if the Pod runs |
Two-zone (1, 1) fixture with minDomains: 3 and maxSkew: 1 | Both spread targets are rejected; scheduler diagnostics support the refusal |
| Individually feasible hard constraints with an empty intersection | Combined calculation and scheduler evidence identify the conflict |
| Equivalent soft-spread case | Evaluate scheduling and preference without asserting a mandatory refusal or exact node |
| Revision grouping or replica removal, when changed | Separate old/new counts and post-removal distribution from application availability |
A Pending phase alone cannot attribute a failure to spreading. Inspect scheduling conditions and events for resource, taint, affinity, storage, or other exclusions, and keep a schedulable positive control. If the candidate changes after a test, rerender and repeat the affected cases. Preserve application readiness and harmless request checks separately from placement evidence.
Failure modes
The selector counts neighboring workloads. Enumerate matching Pods in the namespace and inspect their owners. Narrow the grouping only after the intended sharing policy is clear.
The incoming Pod never counts itself. Compare its admitted labels with the effective selector. Running Pods can still reveal a broken counting contract.
The reviewer counts only domains that already contain Pods. Include eligible empty domains from the node inventory before calculating the global minimum.
minDomains is described as automatic zone recovery. Test the reduced-domain arithmetic and establish the separate capacity-recovery mechanism.
A soft rule is tested as a hard refusal. Review whenUnsatisfiable before asserting a Pending result or a specific placement.
A scale-down imbalance is called a scheduler failure. The guide states that constraints need not remain satisfied after Pods are removed. Require a separate rebalancing procedure if the workload needs one.
FAQ
Does maxSkew: 1 mean one Pod per node?
No. It limits the documented difference for the selected topology. A zone can contain many Pods, and multiple Pods can share a node unless another rule prevents that placement.
Does ScheduleAnyway guarantee that a Pod will run?
No. It makes the spread rule a preference. Resource shortages and other hard scheduling rules can still prevent assignment.
Does changing the constraint rebalance running Pods?
Do not rely on it to do so. The constraint guides incoming scheduling decisions, and the documentation warns that removal and scale-down can leave an imbalance. Review any migration or rebalancing action separately.
Should every workload use minDomains: 3?
No. Choose it from the intended response to fewer eligible domains. With a strict skew, the zero-minimum rule can prevent additional placements until the domain inventory changes.
Reader next step
Choose one agent-written topology spread change. Attach the rendered template, effective selector, eligible-domain inventory, and one incoming-placement calculation to its pull request. In the approved disposable environment, verify a permitted placement and a targeted refusal or selector-mismatch case. Keep Pod UIDs, node labels, scheduler diagnostics, and observation times with the candidate so the reviewer can reproduce the decision.