Topology Keys in Affinity
What you'll learn: How topology keys define the "boundaries" within which Kubernetes evaluates pod affinity and anti-affinity rules.
What is a Topology Key?
When you create affinity or anti-affinity rules, you're telling Kubernetes to place pods together or apart — but where exactly? A topology key is a node label that defines the scheduling domain or "grouping" for these rules. It tells Kubernetes: "evaluate my affinity rule within this boundary."
Common topology keys include:
topology.kubernetes.io/zone(availability zones)topology.kubernetes.io/region(cloud regions)kubernetes.io/hostname(individual nodes)
How It Works
Think of topology keys like organizational categories for your nodes. Imagine you have nodes labeled with zones: zone=us-east-1a, zone=us-east-1b, etc.
When you set topologyKey: topology.kubernetes.io/zone in a pod anti-affinity rule, Kubernetes groups all nodes by their zone label. The anti-affinity rule then means: "don't schedule this pod in the same zone as matching pods."
If you used topologyKey: kubernetes.io/hostname instead, the boundary shrinks to individual hosts — "don't schedule on the same node as matching pods."
Choosing the Right Topology Key
kubernetes.io/hostname: Spread pods across different nodes (finest granularity)topology.kubernetes.io/zone: Spread pods across availability zones (high availability)topology.kubernetes.io/region: Spread pods across entire regions (disaster recovery)
The topology key essentially answers: "What does 'together' or 'apart' mean for my workload?"
Key Takeaway: Topology keys define the scheduling domain boundaries for affinity rules — they transform abstract "together/apart" requirements into concrete geographical or logical groupings like zones, regions, or individual hosts.