diff --git a/content/en/docs/concepts/services-networking/endpoint-slices.md b/content/en/docs/concepts/services-networking/endpoint-slices.md index a398e61d072b0..fdcbd0ed50f87 100644 --- a/content/en/docs/concepts/services-networking/endpoint-slices.md +++ b/content/en/docs/concepts/services-networking/endpoint-slices.md @@ -3,7 +3,7 @@ reviewers: - freehan title: EndpointSlices content_type: concept -weight: 35 +weight: 45 --- diff --git a/content/en/docs/concepts/services-networking/service-topology.md b/content/en/docs/concepts/services-networking/service-topology.md index 4a97074e1794b..e906dff81d1c5 100644 --- a/content/en/docs/concepts/services-networking/service-topology.md +++ b/content/en/docs/concepts/services-networking/service-topology.md @@ -2,12 +2,7 @@ reviewers: - johnbelamaric - imroc -title: Service Topology -feature: - title: Service Topology - description: > - Routing of service traffic based upon cluster topology. - +title: Topology-aware traffic routing with topology keys content_type: concept weight: 10 --- @@ -19,10 +14,10 @@ weight: 10 {{< note >}} -This feature, specifically the alpha topologyKeys API, is deprecated in -Kubernetes v1.21. [Topology Aware -Hints](/docs/concepts/services-networking/topology-aware-hints) was introduced -in Kubernetes v1.21 and provides similar functionality. +This feature, specifically the alpha `topologyKeys` API, is deprecated since +Kubernetes v1.21. +[Topology Aware Hints](/docs/concepts/services-networking/topology-aware-hints/), +introduced in Kubernetes v1.21, provide similar functionality. {{}} @@ -32,33 +27,32 @@ preferentially routed to endpoints that are on the same Node as the client, or in the same availability zone. - -## Introduction +## Topology-aware traffic routing 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. - +any backend address for the Service. Kubernetes 1.7 made it possible to +route "external" traffic to the Pods running on the same Node that received the +traffic. For `ClusterIP` Services, the equivalent same-node preference for +routing wasn't possible; nor could you configure your cluster to favor routing +to endpoints within the same zone. +By setting `topologyKeys` on a Service, you're able to define a policy for routing +traffic based upon the Node labels for the originating and destination Nodes. + +The label matching between the source and destination lets you, as a cluster +operator, designate sets of Nodes that are "closer" and "farther" from one another. +You can define labels to represent whatever metric makes sense for your own +requirements. +In public clouds, for example, you might prefer to keep network traffic within the +same zone, because interzonal traffic has a cost associated with it (and intrazonal +traffic typically does not). Other common needs include being able to route traffic +to a local Pod managed by a DaemonSet, or directing traffic to Nodes connected to the +same top-of-rack switch for the lowest latency. ## Using Service Topology -If your cluster has Service Topology enabled, you can control Service traffic +If your cluster has the `ServiceTopology` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) 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 @@ -209,4 +203,3 @@ spec: * Read about [enabling Service Topology](/docs/tasks/administer-cluster/enabling-service-topology) * Read [Connecting Applications with Services](/docs/concepts/services-networking/connect-applications-service/) - diff --git a/content/en/docs/concepts/services-networking/service-traffic-policy.md b/content/en/docs/concepts/services-networking/service-traffic-policy.md index d69610eabca5a..fb55a3d833e8a 100644 --- a/content/en/docs/concepts/services-networking/service-traffic-policy.md +++ b/content/en/docs/concepts/services-networking/service-traffic-policy.md @@ -3,6 +3,7 @@ reviewers: - maplain title: Service Internal Traffic Policy content_type: concept +weight: 45 --- @@ -19,15 +20,21 @@ cluster. This can help to reduce costs and improve performance. ## Using Service Internal Traffic Policy -You can enable Internal Traffic Policy for a Service by setting the -`spec.internalTrafficPolicy` to "Local". This tells kube-proxy to only use node -local endpoints for cluster internal traffic. Importantly, for pods on nodes with -no endpoints for a given Service, the Service will behave as if it has zero -endpoints (for Pods on this node) even if the service does have endpoints on other -nodes. +Once you have enabled the `ServiceInternalTrafficPolicy` +[feature gate](/docs/reference/command-line-tools-reference/feature-gates/), +you can enable an internal-only traffic policy for a +{{< glossary_tooltip text="Services" term_id="service" >}}, by setting its +`.spec.internalTrafficPolicy` to `Local`. +This tells kube-proxy to only use node local endpoints for cluster internal traffic. -The following example shows what a Service looks like when internalTrafficPolicy -is set to "Local": +{{< note >}} +For pods on nodes with no endpoints for a given Service, the Service +behaves as if it has zero endpoints (for Pods on this node) even if the service +does have endpoints on other nodes. +{{< /note >}} + +The following example shows what a Service looks like when you set +`.spec.internalTrafficPolicy` to `Local`: ```yaml apiVersion: v1 @@ -44,19 +51,19 @@ spec: internalTrafficPolicy: Local ``` -## How it Works +## How it works -kube-proxy filters the endpoints it routes to based on the -`spec.internalTrafficPolicy` setting. When it's "Local", only node local -endpoints are considered. When it's "Cluster" or missing, all endpoints are +The kube-proxy filters the endpoints it routes to based on the +`spec.internalTrafficPolicy` setting. When it's set to `Local`, only node local +endpoints are considered. When it's `Cluster` or missing, all endpoints are considered. -When the feature gate `ServiceInternalTrafficPolicy` is on, -`spec.internalTrafficPolicy` defaults to "Cluster". +When the [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) +`ServiceInternalTrafficPolicy` is enabled, `spec.internalTrafficPolicy` defaults to "Cluster". ## Constraints * Service Internal Traffic Policy is not used when `externalTrafficPolicy` is set - to "Local" on a Service. It is possible to use both features in the same cluster + to `Local` on a Service. It is possible to use both features in the same cluster on different Services, just not on the same Service. ## {{% heading "whatsnext" %}} diff --git a/content/en/docs/concepts/services-networking/topology-aware-hints.md b/content/en/docs/concepts/services-networking/topology-aware-hints.md index ef1d3217c83ee..c2c15878ff72a 100644 --- a/content/en/docs/concepts/services-networking/topology-aware-hints.md +++ b/content/en/docs/concepts/services-networking/topology-aware-hints.md @@ -3,7 +3,7 @@ reviewers: - robscott title: Topology Aware Hints content_type: concept -weight: 10 +weight: 45 --- @@ -13,9 +13,11 @@ weight: 10 _Topology Aware Hints_ enable topology aware routing by including suggestions for how clients should consume endpoints. This approach adds metadata to enable -consumers of Endpoint(Slice) to be able to route traffic closer to where it is -originated. For example, users can route traffic within a locality to reduce -costs and improve performance. +consumers of EndpointSlice and / or and Endpoints objects, so that traffic to +those network endpoints can be routed closer to where it originated. + +For example, you can route traffic within a locality to reduce +costs, or to improve network performance. @@ -24,26 +26,28 @@ costs and improve performance. Kubernetes clusters are increasingly deployed in multi-zone environments. _Topology Aware Hints_ provides a mechanism to help keep traffic within the zone it originated from. This concept is commonly referred to as "Topology Aware -Routing". When calculating the endpoints for a Service, the EndpointSlice -controller considers the topology (region and zone) of each endpoint and -populates the hints field to allocate it to a zone. These hints are then -consumed by components like kube-proxy as they configure how requests are -routed. +Routing". When calculating the endpoints for a {{< glossary_tooltip term_id="Service" >}}, +the EndpointSlice controller considers the topology (region and zone) of each endpoint +and populates the hints field to allocate it to a zone. +Cluster components such as the {{< glossary_tooltip term_id="kube-proxy" text="kube-proxy" >}} +can then consume those hints, and use them to influence how traffic to is routed +(favoring topologically closer endpoints). ## Using Topology Aware Hints -You can enable Topology Aware Hints for a Service by setting the +If you have [enabled](/docs/tasks/administer-cluster/enabling-topology-aware-hints) the +overall feature, you can activate Topology Aware Hints for a Service by setting the `service.kubernetes.io/topology-aware-hints` annotation to `auto`. This tells the EndpointSlice controller to set topology hints if it is deemed safe. Importantly, this does not guarantee that hints will always be set. -## How it Works +## How it works {#implementation} The functionality enabling this feature is split into two components: The -EndpointSlice controller and Kube-Proxy. This provides a high level overview of -how each component implements this feature. +EndpointSlice controller and the kube-proxy. This section provides a high level overview +of how each component implements this feature. -### EndpointSlice controller +### EndpointSlice controller {#implementation-control-plane} The EndpointSlice controller is responsible for setting hints on EndpointSlices when this feature is enabled. The controller allocates a proportional amount of @@ -80,29 +84,29 @@ endpoints: - name: "zone-a" ``` -### Kube-Proxy +### kube-proxy {#implementation-kube-proxy} -Kube-Proxy filters the endpoints it routes to based on the hints set by the -EndpointSlice controller. In most cases, this means that kube-proxy will route -to endpoints in the same zone. Sometimes the controller allocates endpoints from -a different zone to ensure more even distribution of endpoints between zones. +The kube-proxy component filters the endpoints it routes to based on the hints set by +the EndpointSlice controller. In most cases, this means that the kube-proxy is able +to route traffic to endpoints in the same zone. Sometimes the controller allocates endpoints +from a different zone to ensure more even distribution of endpoints between zones. This would result in some traffic being routed to other zones. ## Safeguards The Kubernetes control plane and the kube-proxy on each node apply some safeguard rules before using Topology Aware Hints. If these don't check out, -kube-proxy selects endpoints from anywhere in your cluster, regardless of the +the kube-proxy selects endpoints from anywhere in your cluster, regardless of the zone. 1. **Insufficient number of endpoints:** If there are less endpoints than zones - in a cluster, the controller will not assign any hints. + in a cluster, the controller will not assign any hints. 2. **Impossible to achieve balanced allocation:** In some cases, it will be impossible to achieve a balanced allocation of endpoints among zones. For example, if zone-a is twice as large as zone-b, but there are only 2 endpoints, an endpoint allocated to zone-a may receive twice as much traffic - as zone-b. The controller wil not assign hints if it can't get this "expected + as zone-b. The controller does not assign hints if it can't get this "expected overload" value below an acceptable threshold for each zone. Importantly this is not based on real-time feedback. It is still possible for individual endpoints to become overloaded. @@ -113,14 +117,14 @@ zone. hints and so kube-proxy does not filter endpoints by zone. 4. **One or more endpoints does not have a zone hint:** When this happens, - kube-proxy assumes that a transition from or to Topology Aware Hints is + the kube-proxy assumes that a transition from or to Topology Aware Hints is underway. Filtering endpoints for a Service in this state would be dangerous - so Kube-Proxy falls back to using all endpoints. + so the kube-proxy falls back to using all endpoints. -5. **A zone is not represented in hints:** If kube-proxy is unable to find at - least one endpoint with a hint targeting the zone it is running in, it will - fall back to using endpoints from all zones. This is most likely to happen as - a new zone is being added to a cluster. +5. **A zone is not represented in hints:** If the kube-proxy is unable to find + at least one endpoint with a hint targeting the zone it is running in, it falls + to using endpoints from all zones. This is most likely to happen as you add + a new zone into your existing cluster. ## Constraints @@ -152,5 +156,5 @@ zone. ## {{% heading "whatsnext" %}} -* Read about [enabling Topology Aware Hints](/docs/tasks/administer-cluster/enabling-topology-aware-hints) +* Read about [enabling Topology Aware Hints](/docs/tasks/administer-cluster/enabling-topology-aware-hints/) * Read [Connecting Applications with Services](/docs/concepts/services-networking/connect-applications-service/) diff --git a/content/en/docs/tasks/administer-cluster/enabling-service-topology.md b/content/en/docs/tasks/administer-cluster/enabling-service-topology.md index 6043c9fdec622..8fd39a7e509dd 100644 --- a/content/en/docs/tasks/administer-cluster/enabling-service-topology.md +++ b/content/en/docs/tasks/administer-cluster/enabling-service-topology.md @@ -5,55 +5,51 @@ reviewers: - imroc title: Enabling Service Topology content_type: task +min-kubernetes-server-version: 1.17 --- {{< feature-state for_k8s_version="v1.21" state="deprecated" >}} -This feature, specifically the alpha topologyKeys API, is deprecated in -Kubernetes v1.21. [Topology Aware -Hints](/docs/concepts/services-networking/topology-aware-hints) was introduced -in Kubernetes v1.21 and provides similar functionality. +This feature, specifically the alpha `topologyKeys` field, is deprecated since +Kubernetes v1.21. +[Topology Aware Hints](/docs/concepts/services-networking/topology-aware-hints/), +introduced in Kubernetes v1.21, provide similar functionality. -## {{% heading "prerequisites" %}} - - {{< include "task-tutorial-prereqs.md" >}} {{< version-check >}} - - - - -## Introduction - -_Service Topology_ enables a service to route traffic based upon the Node +_Service Topology_ enables a {{< glossary_tooltip term_id="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. -## Prerequisites +## {{% heading "prerequisites" %}} + + {{< include "task-tutorial-prereqs.md" >}} {{< version-check >}} The following prerequisites are needed in order to enable topology aware service routing: - * Kubernetes 1.17 or later - * {{< glossary_tooltip text="Kube-proxy" term_id="kube-proxy" >}} running in iptables mode or IPVS mode - * Enable [Endpoint Slices](/docs/concepts/services-networking/endpoint-slices/) + * Kubernetes v1.17 or later + * Configure {{< glossary_tooltip text="kube-proxy" term_id="kube-proxy" >}} to run in iptables mode or IPVS mode + + + ## Enable Service Topology -{{< feature-state for_k8s_version="v1.17" state="alpha" >}} +{{< feature-state for_k8s_version="v1.21" state="deprecated" >}} -To enable service topology, enable the `ServiceTopology` and `EndpointSlice` feature gate for all Kubernetes components: +To enable service topology, enable the `ServiceTopology` +[feature gate](/docs/reference/command-line-tools-reference/feature-gates/) for all Kubernetes components: ``` ---feature-gates="ServiceTopology=true,EndpointSlice=true" +--feature-gates="ServiceTopology=true` ``` - ## {{% heading "whatsnext" %}} - -* Read about the [Service Topology](/docs/concepts/services-networking/service-topology) concept -* Read about [Endpoint Slices](/docs/concepts/services-networking/endpoint-slices) +* Read about [Topology Aware Hints](/docs/concepts/services-networking/topology-aware-hints/), the replacement for the `topologyKeys` field. +* Read about [EndpointSlices](/docs/concepts/services-networking/endpoint-slices/) +* Read about the [Service Topology](/docs/concepts/services-networking/service-topology/) concept * Read [Connecting Applications with Services](/docs/concepts/services-networking/connect-applications-service/) diff --git a/content/en/docs/tasks/administer-cluster/enabling-topology-aware-hints.md b/content/en/docs/tasks/administer-cluster/enabling-topology-aware-hints.md index 4222738a4f57f..919f522c7c492 100644 --- a/content/en/docs/tasks/administer-cluster/enabling-topology-aware-hints.md +++ b/content/en/docs/tasks/administer-cluster/enabling-topology-aware-hints.md @@ -10,8 +10,9 @@ min-kubernetes-server-version: 1.21 {{< feature-state for_k8s_version="v1.21" state="alpha" >}} _Topology Aware Hints_ enable topology aware routing with topology hints -included in EndpointSlices. This approach tries to keep traffic close to where -it originated from. This can result in decreased costs and improved performance. +included in {{< glossary_tooltip text="EndpointSlices" term_id="endpoint-slice" >}}. +This approach tries to keep traffic close to where it originated from; +you might do this to reduce costs, or to improve network performance. ## {{% heading "prerequisites" %}} @@ -19,13 +20,13 @@ it originated from. This can result in decreased costs and improved performance. The following prerequisite is needed in order to enable topology aware hints: -* {{< glossary_tooltip text="Kube-proxy" term_id="kube-proxy" >}} running in +* Configure the {{< glossary_tooltip text="kube-proxy" term_id="kube-proxy" >}} to run in iptables mode or IPVS mode * Ensure that you have not disabled EndpointSlices ## Enable Topology Aware Hints -To enable service topology, enable the `TopologyAwareHints` [feature +To enable service topology hints, enable the `TopologyAwareHints` [feature gate](docs/reference/command-line-tools-reference/feature-gates/) for the kube-apiserver, kube-controller-manager, and kube-proxy: