Topology‑Aware Service Routing in Kubernetes v1.17

In this technical overview, the author (roc from Tencent Cloud Container Service) introduces the Kubernetes v1.17 feature "Topology‑Aware Service Routing", which enables services to forward traffic to endpoints that are topologically close to the requesting node.

Key terminology is defined: a topology domain represents a logical location in a cluster (node, rack, zone, region, etc.); an endpoint is an IP + port of a pod; a service groups endpoints and forwards traffic to one of them.

The motivation is to avoid the default equal‑probability load‑balancing that can send requests to distant endpoints, causing higher latency and extra traffic costs. By preferring nearby endpoints, network performance improves.

Existing affinity mechanisms (node affinity, pod affinity/anti‑affinity, volume‑topology‑aware scheduling, local persistent volumes) address scheduling and storage, but Kubernetes lacked network‑affinity capabilities. This feature fills that gap.

Implementation details: kube‑proxy watches the API server for service and endpoint information and writes iptables or IPVS rules. The crucial step is filtering endpoints based on whether they share the same topology domain as the current node. Endpoint topology data is obtained from node labels such as kubernetes.io/hostname , failure-domain.beta.kubernetes.io/zone (renamed to topology.kubernetes.io/zone in v1.17), and failure-domain.beta.kubernetes.io/region (renamed to topology.kubernetes.io/region ). EndpointSlice, introduced in v1.16 and promoted to beta in v1.17, carries these labels for each endpoint, allowing the service router to perform the topology‑aware selection.

To enable the feature, both ServiceTopology and EndpointSlice feature gates must be turned on (e.g., --feature-gates="ServiceTopology=true,EndpointSlice=true" ). In the Service spec, a topologyKeys array defines the priority of topology domains to consider, for example:

apiVersion: v1
kind: Service
metadata:
  name: nginx
spec:
  type: ClusterIP
  ports:
  - name: http
    port: 80
    protocol: TCP
    targetPort: 80
  selector:
    app: nginx
  topologyKeys: ["kubernetes.io/hostname", "topology.kubernetes.io/zone", "*"]

The routing logic checks the list in order: first it tries to find an endpoint on the same node, then in the same zone, and finally falls back to any endpoint using the wildcard * . The feature currently does not support headless services; support is planned for a later beta.

Prerequisites include a cluster version ≥ v1.17, kube‑proxy running in iptables or IPVS mode, and EndpointSlice enabled. Constraints are that topologyKeys cannot be used together with externalTrafficPolicy=Local , keys must be valid label names, and at most 16 keys may be defined.

The development story recounts early designs that watched node metadata, later switched to watching EndpointSlice to reduce overhead, and finally merged into the main codebase after several design iterations.

Overall, topology‑aware service routing reduces latency and improves network efficiency for Kubernetes workloads, and it is slated to appear as an alpha feature in the December 2020 release of Kubernetes v1.17.