Course contentsShow
← Cloud and Infrastructure
Lesson 1353 of 2,98927. Kubernetes Scheduling and ResourcesFree lesson

Topology Keys in Affinity

Understand how topologyKey defines scheduling domains like zones, regions, or hosts.

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.