Kubernetes Service Topology Awareness

Kubernetes Service Topology Awareness refers to the capability of Service traffic routing to take the physical or logical placement of nodes — zone, region, or other topology labels — into account when selecting a backend endpoint, rather than treating every ready endpoint as equally preferable regardless of where it happens to run.

Why Topology Matters for Routing

Cross-Zone Cost and Latency

In clusters spanning multiple availability zones, a Service with no topology awareness routes traffic to any ready backend cluster-wide with equal probability, meaning a substantial fraction of internal traffic crosses zone boundaries even when a perfectly good backend exists in the same zone as the caller. Cross-zone traffic typically carries both added latency and, on most cloud providers, direct data transfer cost, making topology-blind routing wasteful at scale.

Failure Domain Alignment

Beyond cost, topology-aware routing keeps a request's full path within a single failure domain when possible, meaning a zone-level outage affecting the caller is less likely to also require healthy communication with a backend in an unaffected but topologically distant zone, simplifying reasoning about blast radius during partial outages.

Node Topology Labels

The Underlying Topology Signal

Topology awareness relies on standard labels automatically applied to nodes by the cloud provider or cluster infrastructure, most commonly topology.kubernetes.io/zone and topology.kubernetes.io/region, which EndpointSlices inherit for each endpoint based on the node the corresponding pod is running on.

kubectl get nodes -L topology.kubernetes.io/zone

Endpoint-Level Zone Hints

Each entry in an EndpointSlice can carry a hints field indicating which zone(s) that endpoint should preferentially serve, populated by the control plane based on the proportion of endpoints and traffic expected per zone, giving kube-proxy and other consumers the information needed to prefer same-zone routing without needing to separately query node topology themselves.

endpoints:
  - addresses:
      - "10.244.2.31"
    zone: us-east-1a
    hints:
      forZones:
        - name: us-east-1a

Configuring Topology-Aware Routing

trafficDistribution: PreferClose

The primary mechanism for enabling topology-aware behavior on a Service is the trafficDistribution field, set to PreferClose, which instructs routing to favor endpoints in the same zone as the originating node whenever a suitable endpoint exists there, falling back to endpoints in other zones only when no local option is available.

apiVersion: v1
kind: Service
metadata:
  name: ledger-api
spec:
  trafficDistribution: PreferClose
  selector:
    app: ledger-api
  ports:
    - port: 80
      targetPort: 8080

Fallback Behavior Preserves Availability

Topology awareness is designed to degrade gracefully rather than fail closed: if a zone temporarily has no ready backends at all, traffic is routed to the nearest available zone with capacity instead of being dropped, meaning topology preference never comes at the expense of basic availability.

Interaction With Endpoint Distribution

Uneven Endpoint Counts Across Zones

Topology-aware routing works best when backend pods are spread proportionally across zones relative to the traffic originating from each; if one zone has a large caller population but very few backing pods, strict same-zone preference could overload the small local backend set, which is why the control plane's hinting logic accounts for relative endpoint proportions rather than applying a naive same-zone-only rule.

Pod Anti-Affinity as a Complementary Practice

Because topology-aware routing assumes a reasonable spread of backend pods across zones to be effective, it is commonly paired with pod topology spread constraints or anti-affinity rules on the Deployment itself, ensuring the endpoint distribution topology awareness relies on actually exists in practice rather than being incidental.

topologySpreadConstraints:
  - maxSkew: 1
    topologyKey: topology.kubernetes.io/zone
    whenUnsatisfiable: DoNotSchedule
    labelSelector:
      matchLabels:
        app: ledger-api

Observability of Topology Behavior

Verifying Same-Zone Routing in Practice

Confirming that topology-aware routing is functioning as intended typically requires correlating request-level tracing or access logs with the zone of both the calling pod and the responding pod, since neither the Service object nor kube-proxy's local state directly reports an aggregate "percentage of same-zone traffic" metric on its own.

kubectl get pods -o custom-columns=NAME:.metadata.name,NODE:.spec.nodeName
kubectl get nodes -L topology.kubernetes.io/zone