Service Topology


Service Topology

FEATURE STATE: Kubernetes v1.17 alpha
This feature is currently in a alpha state, meaning:

  • The version names contain alpha (e.g. v1alpha1).
  • Might be buggy. Enabling the feature may expose bugs. Disabled by default.
  • Support for feature may be dropped at any time without notice.
  • The API may change in incompatible ways in a later software release without notice.
  • Recommended for use only in short-lived testing clusters, due to increased risk of bugs and lack of long-term support.

Service Topology enables a service to route traffic based upon the Node topology of the cluster. For example, a service can specify that traffic be preferentially routed to endpoints that are on the same Node as the client, or in the same availability zone.


By default, traffic sent to a ClusterIP or NodePort Service may be routed to any backend address for the Service. Since Kubernetes 1.7 it has been possible to route “external” traffic to the Pods running on the Node that received the traffic, but this is not supported for ClusterIP Services, and more complex topologies — such as routing zonally — have not been possible. The Service Topology feature resolves this by allowing the Service creator to define a policy for routing traffic based upon the Node labels for the originating and destination Nodes.

By using Node label matching between the source and destination, the operator may designate groups of Nodes that are “closer” and “farther” from one another, using whatever metric makes sense for that operator’s requirements. For many operators in public clouds, for example, there is a preference to keep service traffic within the same zone, because interzonal traffic has a cost associated with it, while intrazonal traffic does not. Other common needs include being able to route traffic to a local Pod managed by a DaemonSet, or keeping traffic to Nodes connected to the same top-of-rack switch for the lowest latency.


The following prerequisites are needed in order to enable topology aware service routing:

  • Kubernetes 1.17 or later
  • Kube-proxy running in iptables mode or IPVS mode
  • Enable Endpoint Slices

Enable Service Topology

To enable service topology, enable the ServiceTopology feature gate for kube-apiserver and kube-proxy:


Using Service Topology

If your cluster has Service Topology enabled, you can control Service traffic routing by specifying the topologyKeys field on the Service spec. This field is a preference-order list of Node labels which will be used to sort endpoints when accessing this Service. Traffic will be directed to a Node whose value for the first label matches the originating Node’s value for that label. If there is no backend for the Service on a matching Node, then the second label will be considered, and so forth, until no labels remain.

If no match is found, the traffic will be rejected, just as if there were no backends for the Service at all. That is, endpoints are chosen based on the first topology key with available backends. If this field is specified and all entries have no backends that match the topology of the client, the service has no backends for that client and connections should fail. The special value "*" may be used to mean “any topology”. This catch-all value, if used, only makes sense as the last value in the list.

If topologyKeys is not specified or empty, no topology constraints will be applied.

Consider a cluster with Nodes that are labeled with their hostname, zone name, and region name. Then you can set the topologyKeys values of a service to direct traffic as follows.

  • Only to endpoints on the same node, failing if no endpoint exists on the node: [""].
  • Preferentially to endpoints on the same node, falling back to endpoints in the same zone, followed by the same region, and failing otherwise: ["", "", ""]. This may be useful, for example, in cases where data locality is critical.
  • Preferentially to the same zone, but fallback on any available endpoint if none are available within this zone: ["", "*"].


  • Service topology is not compatible with externalTrafficPolicy=Local, and therefore a Service cannot use both of these features. It is possible to use both features in the same cluster on different Services, just not on the same Service.

  • Valid topology keys are currently limited to,, and, but will be generalized to other node labels in the future.

  • Topology keys must be valid label keys and at most 16 keys may be specified.

  • The catch-all value, "*", must be the last value in the topology keys, if it is used.