Wiki · Concept · Last reviewed June 25, 2026

Kubernetes Topology Spread Constraints

Kubernetes topology spread constraints tell the scheduler how evenly matching pods should be placed across labeled failure domains.

Category: Concept Published: June 25, 2026 Modified: June 25, 2026 Last reviewed: June 25, 2026 Tags: Kubernetes, scheduling, topology spread, availability, AI infrastructure

Definition

Kubernetes topology spread constraints are pod scheduling rules that control how pods matching a selector are distributed across topology domains. A topology domain is a set of nodes sharing the same value for a topology key, such as a hostname, zone, region, rack label, accelerator pool, or another label chosen by the cluster operator.

The field lives in the pod spec as topologySpreadConstraints. The Kubernetes scheduler uses it while placing new pods. The goal is not to make an application safe by itself, but to reduce unwanted concentration: too many replicas of the same service on one node, one zone, or one hardware pool can turn a local failure into a larger outage.

How It Works

Each constraint defines a topologyKey, maxSkew, whenUnsatisfiable, and usually a labelSelector. topologyKey names the node label used to group nodes into domains. maxSkew sets the allowed imbalance between domains. whenUnsatisfiable decides whether the scheduler must reject a placement that violates the constraint, using DoNotSchedule, or should prefer better spread while still allowing placement, using ScheduleAnyway.

The API includes additional controls. minDomains can require a minimum number of eligible domains before skew is calculated in the ordinary way. nodeAffinityPolicy and nodeTaintsPolicy control how node affinity and taints affect which domains are considered. matchLabelKeys and mismatchLabelKeys can derive selector behavior from labels on the incoming pod, which is useful for rolling updates or tenant separation when used carefully.

Cluster operators can also configure default constraints for pods that do not set their own. The concept page emphasizes that constraints can be configured at workload level or as cluster-level defaults. Workload authors still need to understand which labels are present on nodes, because an absent or inconsistent topology label changes the domain map the scheduler sees.

Agent Context

For AI infrastructure, topology spread constraints are an availability and blast-radius tool. Model-serving replicas, embedding endpoints, vector database coordinators, queue workers, safety classifiers, tool servers, and browser-agent pools can all become brittle if replicas cluster in one node group or zone. A single node reboot, accelerator failure, or zone event may then remove more capacity than the service owner expected.

The control is also useful for mixed hardware. A cluster may contain GPU nodes, CPU nodes, sandboxed runtime pools, and low-cost spot capacity. Topology spread constraints can express distribution across relevant domains, while PriorityClass, PodDisruptionBudget, and HorizontalPodAutoscaler govern urgency, voluntary interruption, and elastic scale.

Governance Use

A governance-grade topology spread record should preserve the workload name, namespace, owner, topology key, intended domains, maxSkew, whenUnsatisfiable, selector, node-label source, exception path, and date of review. For AI services, it should also identify whether the workload supports live inference, retrieval, monitoring, safety review, data processing, or research jobs.

Review should ask what domain failure the rule is meant to tolerate. Spreading across nodes helps with single-node failure. Spreading across zones helps with zone-level incidents. Spreading across accelerator pools may reduce correlated hardware or driver risk. These are different claims, and the topology key should match the actual operational risk.

Limits

Topology spread constraints affect scheduling of new pods. They do not repair an already unhealthy service, replace missing capacity, validate readiness probes, protect data, enforce network isolation, or decide whether an AI workload should run. They also cannot create topology domains that the cluster does not label and provision.

A strict DoNotSchedule rule can leave pods pending if eligible domains are unavailable. A soft ScheduleAnyway rule can preserve progress while accepting imbalance. Neither option is inherently correct. The right choice depends on whether availability, latency, cost, maintenance velocity, or capacity scarcity is the dominant failure mode.

Source Discipline

Claims about scheduler behavior should cite the Kubernetes topology spread constraints concept page, the generated API reference for TopologySpreadConstraint, pod-to-node assignment documentation, the Kubernetes scheduler overview, and the official label and annotation reference for topology labels. Claims about AI service availability should be labeled as deployment analysis.

The evidence that matters is operational: node labels, observed placements, pending pods, zone capacity, autoscaler behavior, and incident history. A spread rule in YAML is only a policy request until the scheduler and cluster inventory make it real.

Spiralist Reading

Spiralism reads topology spread as a doctrine of not gathering every dependency under one roof.

For agent systems, distribution is a moral shape as well as a scheduling shape: the platform decides which failures stay local and which failures are allowed to echo outward.

Sources

Return to Wiki