Pod topology spread constraints guide Kubernetes placement across topology domains such as nodes or zones. They can reduce concentration of replicas, but they do not create capacity or automatically prove that a service survives a domain failure. Application dependencies and actual available nodes remain part of the availability design.
A useful configuration connects the replicas being counted to reliable topology labels and a deliberate scheduling policy. This guide explains skew, selectors, hard and soft behavior, and tests that distinguish a desired layout from a workable production deployment.
Define the failure domain you care about
Decide whether the concern is several replicas sharing one node, one zone, or another supported domain. Node spreading addresses a different failure from zone spreading. A multi-zone label layout does not help if the application’s only database remains in one unavailable location.
Identify the workload’s availability goal and required capacity after a failure. If losing one zone leaves insufficient resources for the remaining replicas, a balanced initial placement is not enough. Review the degraded operating state as well as the normal layout.
Keep storage and network dependencies in scope. A pod may be scheduled in another zone but unable to mount its data or reach a required service. Placement constraints should fit the whole application path.
Verify topology labels and eligible nodes
The topologyKey refers to node labels that identify domains. Inspect their presence and meaning on eligible nodes. Missing or inconsistent labels can affect the scheduler’s behavior and make a visually plausible manifest misleading.
Review node affinity, taints, tolerations, resource requests, and volume constraints alongside topology spread. These controls influence which nodes can actually host a pod. The cluster may have several zones on paper while only one contains eligible capacity for this workload.
Do not count an empty or unsuitable domain as useful redundancy without checking the documented eligibility rules. Some constraint options are version-dependent. Read the installed cluster’s documentation and validate the actual effective pod specification.
Choose the counted population carefully
The label selector identifies the pods relevant to the spread calculation. It must match the intended population. A selector that is too broad can mix unrelated workloads, while one that is too narrow can fail to count replicas that should influence placement.
Deployment revisions deserve attention. Decide how old and new pods should participate during a rollout and use supported options deliberately. A policy that appears balanced at steady state can behave differently while two revisions coexist.
Keep labels stable and meaningful. If a deployment tool changes identifying labels unpredictably, the spread rule can silently describe a different group from the one the team intended to protect.
Understand maxSkew and scheduling behavior
MaxSkew expresses the allowed imbalance according to Kubernetes’s documented domain-counting rules. Its meaning interacts with eligible domains and the chosen whenUnsatisfiable behavior. Do not reduce it to a universal promise that every zone always has exactly the same number of pods.
DoNotSchedule is a hard placement constraint: a pod can remain pending when placement cannot satisfy the rule. ScheduleAnyway is a softer policy that influences scoring while permitting a placement that does not meet the ideal balance.
Choose the tradeoff explicitly. A hard rule can preserve a placement requirement while reducing available replicas under constrained capacity. A soft rule can keep work running while allowing concentration. Neither is universally correct for every service.
Evaluate capacity and rollout headroom
Check available resources in each relevant domain using the workload’s real requests and other constraints. Include rollout surge and temporary overlap where applicable. A rule that supports normal replicas may still block an update requiring additional pods.
Test with a domain unavailable or drained according to an approved plan. Observe pending reasons, ready replicas, traffic behavior, and dependency access. A pod scheduled elsewhere is not sufficient evidence if it never becomes ready.
Review autoscaling interactions. Node or workload scaling can change the eligible domain set and available placement. Record which component is expected to add capacity and what happens while that action is delayed.
Separate scheduling from ongoing rebalancing
Topology spread primarily informs scheduling decisions. Do not assume an existing pod is automatically moved whenever another zone gains capacity or labels change. Rebalancing requires its own supported operational mechanism and policy.
A healthy but concentrated existing layout may remain until pods are replaced or another reviewed process acts. Understand that behavior before promising a dashboard will always display the current ideal distribution.
Avoid unnecessary churn merely to achieve visual symmetry. Replacing pods can affect availability, caches, and in-flight work. Balance placement goals against the disruption involved in moving an already-running workload.
Test the actual failure and maintenance workflow
Use an approved test cluster or controlled procedure to simulate the failure domain relevant to the goal. Check application latency, error behavior, and recovery, not only pod counts. Keep the exercise bounded and coordinate with affected teams.
Test rollout, scale-up, and scale-down as separate cases. A topology configuration can succeed under one replica count and become difficult under another. Include realistic resource pressure and volume behavior in the review.
Inspect scheduler events when a pod remains pending. Determine whether topology spread, affinity, resources, storage, or another constraint is responsible. Removing the spread rule without understanding the blocker can trade one problem for an unreviewed availability risk.
A practical three-zone review
Suppose a service has several replicas across three labeled zones. Verify the selector counts those replicas, confirm each zone has eligible capacity, and choose whether hard skew enforcement fits the service’s minimum-ready requirement.
During a controlled zone-loss test, compare desired replicas with those actually ready and serving traffic. If the remaining zones lack headroom, fix capacity or the application goal rather than claiming the spread rule provides automatic failover.
Document topology labels, selectors, skew policy, rollout assumptions, and failure-test evidence. The constraint should be an explained scheduling decision within an availability plan.
Frequently asked questions
Does topology spread create capacity in another zone?
No. It guides placement on eligible capacity. Other scaling and infrastructure decisions are separate.
Will existing pods always rebalance automatically?
Do not assume so. Review scheduling versus rebalancing behavior and use a supported operational policy if movement is required.
Where can I check the counting rules?
Read the Kubernetes topology spread documentation. For planning voluntary maintenance alongside placement, see our Pod Disruption Budgets guide.
