Kubernetes Topology Availability Basics

Kubernetes Topology Availability Basics is the general mechanism underlying every fault-domain spread technique used elsewhere in this knowledge area, covering the full topology spread constraint feature set, including layering multiple constraints across different topology keys, the required-versus-preferred distinction, and the finer-grained fields that control how taints and node affinity interact with spread calculations.

The Topology Key Abstraction

Arbitrary Node Labels as Fault Domains

topologySpreadConstraints:
  - maxSkew: 1
    topologyKey: topology.kubernetes.io/zone

A topologyKey is simply a node label key, zone, region, kubernetes.io/hostname, or any custom label a cluster operator has applied, meaning the topology spread mechanism is not hardcoded to any specific notion of fault domain but generalizes to whatever grouping of nodes is meaningful for a given cluster's actual failure characteristics, including custom labels such as rack or power-domain in an on-premises environment.

Layering Multiple Constraints

Spreading Across Several Dimensions Simultaneously

topologySpreadConstraints:
  - maxSkew: 1
    topologyKey: topology.kubernetes.io/zone
    whenUnsatisfiable: DoNotSchedule
    labelSelector: { matchLabels: { app: web } }
  - maxSkew: 2
    topologyKey: kubernetes.io/hostname
    whenUnsatisfiable: ScheduleAnyway
    labelSelector: { matchLabels: { app: web } }

A pod's specification can declare multiple topology spread constraints simultaneously, each evaluated independently, letting a single workload be spread across zones (a strict requirement) while also being spread across individual nodes within each zone (a softer preference), addressing two distinct fault domain scales at once rather than requiring separate mechanisms for each.

Required vs. Preferred Placement

DoNotSchedule vs. ScheduleAnyway

whenUnsatisfiable: DoNotSchedule

whenUnsatisfiable: ScheduleAnyway

DoNotSchedule makes the constraint a hard requirement, refusing to schedule a pod at all if satisfying it is impossible, guaranteeing spread at the cost of potential unschedulability; ScheduleAnyway treats the constraint as a scoring preference the scheduler tries to honor but will override if no compliant placement exists, guaranteeing schedulability at the cost of a spread guarantee that may occasionally be violated under capacity pressure.

minDomains for Guaranteed Domain Coverage

Requiring a Minimum Number of Distinct Domains

topologySpreadConstraints:
  - maxSkew: 1
    minDomains: 3
    topologyKey: topology.kubernetes.io/zone
    whenUnsatisfiable: DoNotSchedule

minDomains requires that at least the specified number of distinct topology domains actually exist and are eligible for scheduling before the constraint can be satisfied, addressing the case where maxSkew alone would be trivially satisfied by concentrating every replica in a single available zone simply because no other zone happens to have any pods yet; minDomains makes the intent "spread across at least three zones" explicit rather than an accidental consequence of maxSkew arithmetic.

Interaction With Taints and Node Affinity

nodeAffinityPolicy and nodeTaintsPolicy

topologySpreadConstraints:
  - maxSkew: 1
    topologyKey: topology.kubernetes.io/zone
    nodeAffinityPolicy: Honor
    nodeTaintsPolicy: Honor

nodeAffinityPolicy: Honor (the default) means only nodes matching the pod's own node affinity rules are counted when computing spread across a topology domain; setting it to Ignore counts all nodes regardless of affinity, which can produce misleading skew calculations if a domain contains many nodes the pod could never actually be scheduled onto anyway. nodeTaintsPolicy applies the analogous distinction for node taints and pod tolerations.

Combining Topology Spread With Pod Affinity/Anti-Affinity

Complementary, Not Redundant, Mechanisms

affinity:
  podAntiAffinity:
    preferredDuringSchedulingIgnoredDuringExecution:
      - weight: 100
        podAffinityTerm:
          labelSelector: { matchLabels: { app: web } }
          topologyKey: kubernetes.io/hostname

While both mechanisms can express "spread these pods apart," topology spread constraints are designed for even distribution across a defined set of domains with quantified skew tolerance, while pod anti-affinity is designed for simpler binary co-location avoidance; using topology spread constraints for the primary even-distribution goal and reserving affinity/anti-affinity for specific co-location rules (never placing two workloads on the same node at all) keeps each mechanism applied to the problem it is actually best suited for.

Relationship to Zone Failure Tolerance and the Reliability Model

Topology availability basics is the general mechanism that zone failure tolerance applies specifically to the zone topology key, and it is the direct implementation of the fault domain hierarchy principle introduced under the broader reliability model: by generalizing to any topology key a cluster chooses to label, this mechanism extends the same spread-based redundancy reasoning from zones down to racks, hosts, or any other fault domain relevant to a specific infrastructure's actual failure characteristics.