Tidy docs about EndpointSlice & related features

content/en/docs/concepts/services-networking/endpoint-slices.md

@@ -3,7 +3,7 @@ reviewers:
 - freehan
 title: EndpointSlices
 content_type: concept
-weight: 35
+weight: 45
 ---
 
 

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.
 
 {{</ note >}}
 
@@ -32,33 +27,32 @@ preferentially routed to endpoints that are on the same Node as the client, or
 in the same availability zone.
 
 
-
 <!-- body -->
 
-## 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 &mdash; such as routing zonally &mdash; 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/)
 
-

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" %}}

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.
 
 <!-- body -->
 
@@ -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/)

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
 ---
 
 <!-- overview -->
 {{< 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 >}}
-
-
-<!-- steps -->
-
-## 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
+
+
+<!-- steps -->
 
 ## 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/)
 
 

content/en/docs/tasks/administer-cluster/enabling-topology-aware-hints.md

@@ -10,22 +10,23 @@ 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" %}}
 
   {{< include "task-tutorial-prereqs.md" >}} {{< version-check >}}
 
 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: