Skip to content

Commit 029c885

Browse files
k8s-ci-robotk8s-ci-robot
authored
Merge pull request #27390 from sftim/20210403_tidy_service_endpoints_docs_1.21
Tidy docs about EndpointSlice & related features
2 parents a2f0abd + c9ca131 commit 029c885

File tree

6 files changed

+106
-105
lines changed

6 files changed

+106
-105
lines changed

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ reviewers:
33
- freehan
44
title: EndpointSlices
55
content_type: concept
6-
weight: 35
6+
weight: 45
77
---
88

99

‎content/en/docs/concepts/services-networking/service-topology.md

Lines changed: 24 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,7 @@
22
reviewers:
33
- johnbelamaric
44
- imroc
5-
title: Service Topology
6-
feature:
7-
title: Service Topology
8-
description: >
9-
Routing of service traffic based upon cluster topology.
10-
5+
title: Topology-aware traffic routing with topology keys
116
content_type: concept
127
weight: 10
138
---
@@ -19,10 +14,10 @@ weight: 10
1914

2015
{{< note >}}
2116

22-
This feature, specifically the alpha topologyKeys API, is deprecated in
23-
Kubernetes v1.21. [Topology Aware
24-
Hints](/docs/concepts/services-networking/topology-aware-hints) was introduced
25-
in Kubernetes v1.21 and provides similar functionality.
17+
This feature, specifically the alpha `topologyKeys` API, is deprecated since
18+
Kubernetes v1.21.
19+
[Topology Aware Hints](/docs/concepts/services-networking/topology-aware-hints/),
20+
introduced in Kubernetes v1.21, provide similar functionality.
2621

2722
{{</ note >}}
2823

@@ -32,33 +27,32 @@ preferentially routed to endpoints that are on the same Node as the client, or
3227
in the same availability zone.
3328

3429

35-
3630
<!-- body -->
3731

38-
## Introduction
32+
## Topology-aware traffic routing
3933

4034
By default, traffic sent to a `ClusterIP` or `NodePort` Service may be routed to
41-
any backend address for the Service. Since Kubernetes 1.7 it has been possible
42-
to route "external" traffic to the Pods running on the Node that received the
43-
traffic, but this is not supported for `ClusterIP` Services, and more complex
44-
topologies &mdash; such as routing zonally &mdash; have not been possible. The
45-
_Service Topology_ feature resolves this by allowing the Service creator to
46-
define a policy for routing traffic based upon the Node labels for the
47-
originating and destination Nodes.
48-
49-
By using Node label matching between the source and destination, the operator
50-
may designate groups of Nodes that are "closer" and "farther" from one another,
51-
using whatever metric makes sense for that operator's requirements. For many
52-
operators in public clouds, for example, there is a preference to keep service
53-
traffic within the same zone, because interzonal traffic has a cost associated
54-
with it, while intrazonal traffic does not. Other common needs include being able
55-
to route traffic to a local Pod managed by a DaemonSet, or keeping traffic to
56-
Nodes connected to the same top-of-rack switch for the lowest latency.
57-
35+
any backend address for the Service. Kubernetes 1.7 made it possible to
36+
route "external" traffic to the Pods running on the same Node that received the
37+
traffic. For `ClusterIP` Services, the equivalent same-node preference for
38+
routing wasn't possible; nor could you configure your cluster to favor routing
39+
to endpoints within the same zone.
40+
By setting `topologyKeys` on a Service, you're able to define a policy for routing
41+
traffic based upon the Node labels for the originating and destination Nodes.
42+
43+
The label matching between the source and destination lets you, as a cluster
44+
operator, designate sets of Nodes that are "closer" and "farther" from one another.
45+
You can define labels to represent whatever metric makes sense for your own
46+
requirements.
47+
In public clouds, for example, you might prefer to keep network traffic within the
48+
same zone, because interzonal traffic has a cost associated with it (and intrazonal
49+
traffic typically does not). Other common needs include being able to route traffic
50+
to a local Pod managed by a DaemonSet, or directing traffic to Nodes connected to the
51+
same top-of-rack switch for the lowest latency.
5852

5953
## Using Service Topology
6054

61-
If your cluster has Service Topology enabled, you can control Service traffic
55+
If your cluster has the `ServiceTopology` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) enabled, you can control Service traffic
6256
routing by specifying the `topologyKeys` field on the Service spec. This field
6357
is a preference-order list of Node labels which will be used to sort endpoints
6458
when accessing this Service. Traffic will be directed to a Node whose value for
@@ -209,4 +203,3 @@ spec:
209203
* Read about [enabling Service Topology](/docs/tasks/administer-cluster/enabling-service-topology)
210204
* Read [Connecting Applications with Services](/docs/concepts/services-networking/connect-applications-service/)
211205
212-

‎content/en/docs/concepts/services-networking/service-traffic-policy.md

Lines changed: 22 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ reviewers:
33
- maplain
44
title: Service Internal Traffic Policy
55
content_type: concept
6+
weight: 45
67
---
78

89

@@ -19,15 +20,21 @@ cluster. This can help to reduce costs and improve performance.
1920

2021
## Using Service Internal Traffic Policy
2122

22-
You can enable Internal Traffic Policy for a Service by setting the
23-
`spec.internalTrafficPolicy` to "Local". This tells kube-proxy to only use node
24-
local endpoints for cluster internal traffic. Importantly, for pods on nodes with
25-
no endpoints for a given Service, the Service will behave as if it has zero
26-
endpoints (for Pods on this node) even if the service does have endpoints on other
27-
nodes.
23+
Once you have enabled the `ServiceInternalTrafficPolicy`
24+
[feature gate](/docs/reference/command-line-tools-reference/feature-gates/),
25+
you can enable an internal-only traffic policy for a
26+
{{< glossary_tooltip text="Services" term_id="service" >}}, by setting its
27+
`.spec.internalTrafficPolicy` to `Local`.
28+
This tells kube-proxy to only use node local endpoints for cluster internal traffic.
2829

29-
The following example shows what a Service looks like when internalTrafficPolicy
30-
is set to "Local":
30+
{{< note >}}
31+
For pods on nodes with no endpoints for a given Service, the Service
32+
behaves as if it has zero endpoints (for Pods on this node) even if the service
33+
does have endpoints on other nodes.
34+
{{< /note >}}
35+
36+
The following example shows what a Service looks like when you set
37+
`.spec.internalTrafficPolicy` to `Local`:
3138

3239
```yaml
3340
apiVersion: v1
@@ -44,19 +51,19 @@ spec:
4451
internalTrafficPolicy: Local
4552
```
4653
47-
## How it Works
54+
## How it works
4855
49-
kube-proxy filters the endpoints it routes to based on the
50-
`spec.internalTrafficPolicy` setting. When it's "Local", only node local
51-
endpoints are considered. When it's "Cluster" or missing, all endpoints are
56+
The kube-proxy filters the endpoints it routes to based on the
57+
`spec.internalTrafficPolicy` setting. When it's set to `Local`, only node local
58+
endpoints are considered. When it's `Cluster` or missing, all endpoints are
5259
considered.
53-
When the feature gate `ServiceInternalTrafficPolicy` is on,
54-
`spec.internalTrafficPolicy` defaults to "Cluster".
60+
When the [feature gate](/docs/reference/command-line-tools-reference/feature-gates/)
61+
`ServiceInternalTrafficPolicy` is enabled, `spec.internalTrafficPolicy` defaults to "Cluster".
5562

5663
## Constraints
5764

5865
* Service Internal Traffic Policy is not used when `externalTrafficPolicy` is set
59-
to "Local" on a Service. It is possible to use both features in the same cluster
66+
to `Local` on a Service. It is possible to use both features in the same cluster
6067
on different Services, just not on the same Service.
6168

6269
## {{% heading "whatsnext" %}}

‎content/en/docs/concepts/services-networking/topology-aware-hints.md

Lines changed: 33 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ reviewers:
33
- robscott
44
title: Topology Aware Hints
55
content_type: concept
6-
weight: 10
6+
weight: 45
77
---
88

99

@@ -13,9 +13,11 @@ weight: 10
1313

1414
_Topology Aware Hints_ enable topology aware routing by including suggestions
1515
for how clients should consume endpoints. This approach adds metadata to enable
16-
consumers of Endpoint(Slice) to be able to route traffic closer to where it is
17-
originated. For example, users can route traffic within a locality to reduce
18-
costs and improve performance.
16+
consumers of EndpointSlice and / or and Endpoints objects, so that traffic to
17+
those network endpoints can be routed closer to where it originated.
18+
19+
For example, you can route traffic within a locality to reduce
20+
costs, or to improve network performance.
1921

2022
<!-- body -->
2123

@@ -24,26 +26,28 @@ costs and improve performance.
2426
Kubernetes clusters are increasingly deployed in multi-zone environments.
2527
_Topology Aware Hints_ provides a mechanism to help keep traffic within the zone
2628
it originated from. This concept is commonly referred to as "Topology Aware
27-
Routing". When calculating the endpoints for a Service, the EndpointSlice
28-
controller considers the topology (region and zone) of each endpoint and
29-
populates the hints field to allocate it to a zone. These hints are then
30-
consumed by components like kube-proxy as they configure how requests are
31-
routed.
29+
Routing". When calculating the endpoints for a {{< glossary_tooltip term_id="Service" >}},
30+
the EndpointSlice controller considers the topology (region and zone) of each endpoint
31+
and populates the hints field to allocate it to a zone.
32+
Cluster components such as the {{< glossary_tooltip term_id="kube-proxy" text="kube-proxy" >}}
33+
can then consume those hints, and use them to influence how traffic to is routed
34+
(favoring topologically closer endpoints).
3235

3336
## Using Topology Aware Hints
3437

35-
You can enable Topology Aware Hints for a Service by setting the
38+
If you have [enabled](/docs/tasks/administer-cluster/enabling-topology-aware-hints) the
39+
overall feature, you can activate Topology Aware Hints for a Service by setting the
3640
`service.kubernetes.io/topology-aware-hints` annotation to `auto`. This tells
3741
the EndpointSlice controller to set topology hints if it is deemed safe.
3842
Importantly, this does not guarantee that hints will always be set.
3943

40-
## How it Works
44+
## How it works {#implementation}
4145

4246
The functionality enabling this feature is split into two components: The
43-
EndpointSlice controller and Kube-Proxy. This provides a high level overview of
44-
how each component implements this feature.
47+
EndpointSlice controller and the kube-proxy. This section provides a high level overview
48+
of how each component implements this feature.
4549

46-
### EndpointSlice controller
50+
### EndpointSlice controller {#implementation-control-plane}
4751

4852
The EndpointSlice controller is responsible for setting hints on EndpointSlices
4953
when this feature is enabled. The controller allocates a proportional amount of
@@ -80,29 +84,29 @@ endpoints:
8084
- name: "zone-a"
8185
```
8286
83-
### Kube-Proxy
87+
### kube-proxy {#implementation-kube-proxy}
8488
85-
Kube-Proxy filters the endpoints it routes to based on the hints set by the
86-
EndpointSlice controller. In most cases, this means that kube-proxy will route
87-
to endpoints in the same zone. Sometimes the controller allocates endpoints from
88-
a different zone to ensure more even distribution of endpoints between zones.
89+
The kube-proxy component filters the endpoints it routes to based on the hints set by
90+
the EndpointSlice controller. In most cases, this means that the kube-proxy is able
91+
to route traffic to endpoints in the same zone. Sometimes the controller allocates endpoints
92+
from a different zone to ensure more even distribution of endpoints between zones.
8993
This would result in some traffic being routed to other zones.
9094
9195
## Safeguards
9296
9397
The Kubernetes control plane and the kube-proxy on each node apply some
9498
safeguard rules before using Topology Aware Hints. If these don't check out,
95-
kube-proxy selects endpoints from anywhere in your cluster, regardless of the
99+
the kube-proxy selects endpoints from anywhere in your cluster, regardless of the
96100
zone.
97101
98102
1. **Insufficient number of endpoints:** If there are less endpoints than zones
99-
in a cluster, the controller will not assign any hints.
103+
in a cluster, the controller will not assign any hints.
100104
101105
2. **Impossible to achieve balanced allocation:** In some cases, it will be
102106
impossible to achieve a balanced allocation of endpoints among zones. For
103107
example, if zone-a is twice as large as zone-b, but there are only 2
104108
endpoints, an endpoint allocated to zone-a may receive twice as much traffic
105-
as zone-b. The controller wil not assign hints if it can't get this "expected
109+
as zone-b. The controller does not assign hints if it can't get this "expected
106110
overload" value below an acceptable threshold for each zone. Importantly this
107111
is not based on real-time feedback. It is still possible for individual
108112
endpoints to become overloaded.
@@ -113,14 +117,14 @@ zone.
113117
hints and so kube-proxy does not filter endpoints by zone.
114118

115119
4. **One or more endpoints does not have a zone hint:** When this happens,
116-
kube-proxy assumes that a transition from or to Topology Aware Hints is
120+
the kube-proxy assumes that a transition from or to Topology Aware Hints is
117121
underway. Filtering endpoints for a Service in this state would be dangerous
118-
so Kube-Proxy falls back to using all endpoints.
122+
so the kube-proxy falls back to using all endpoints.
119123

120-
5. **A zone is not represented in hints:** If kube-proxy is unable to find at
121-
least one endpoint with a hint targeting the zone it is running in, it will
122-
fall back to using endpoints from all zones. This is most likely to happen as
123-
a new zone is being added to a cluster.
124+
5. **A zone is not represented in hints:** If the kube-proxy is unable to find
125+
at least one endpoint with a hint targeting the zone it is running in, it falls
126+
to using endpoints from all zones. This is most likely to happen as you add
127+
a new zone into your existing cluster.
124128

125129
## Constraints
126130

@@ -152,5 +156,5 @@ zone.
152156

153157
## {{% heading "whatsnext" %}}
154158

155-
* Read about [enabling Topology Aware Hints](/docs/tasks/administer-cluster/enabling-topology-aware-hints)
159+
* Read about [enabling Topology Aware Hints](/docs/tasks/administer-cluster/enabling-topology-aware-hints/)
156160
* Read [Connecting Applications with Services](/docs/concepts/services-networking/connect-applications-service/)

‎content/en/docs/tasks/administer-cluster/enabling-service-topology.md

Lines changed: 21 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -5,55 +5,51 @@ reviewers:
55
- imroc
66
title: Enabling Service Topology
77
content_type: task
8+
min-kubernetes-server-version: 1.17
89
---
910

1011
<!-- overview -->
1112
{{< feature-state for_k8s_version="v1.21" state="deprecated" >}}
1213

13-
This feature, specifically the alpha topologyKeys API, is deprecated in
14-
Kubernetes v1.21. [Topology Aware
15-
Hints](/docs/concepts/services-networking/topology-aware-hints) was introduced
16-
in Kubernetes v1.21 and provides similar functionality.
14+
This feature, specifically the alpha `topologyKeys` field, is deprecated since
15+
Kubernetes v1.21.
16+
[Topology Aware Hints](/docs/concepts/services-networking/topology-aware-hints/),
17+
introduced in Kubernetes v1.21, provide similar functionality.
1718

18-
## {{% heading "prerequisites" %}}
19-
20-
{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}}
21-
22-
23-
<!-- steps -->
24-
25-
## Introduction
26-
27-
_Service Topology_ enables a service to route traffic based upon the Node
19+
_Service Topology_ enables a {{< glossary_tooltip term_id="service">}} to route traffic based upon the Node
2820
topology of the cluster. For example, a service can specify that traffic be
2921
preferentially routed to endpoints that are on the same Node as the client, or
3022
in the same availability zone.
3123

32-
## Prerequisites
24+
## {{% heading "prerequisites" %}}
25+
26+
{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}}
3327

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

37-
* Kubernetes 1.17 or later
38-
* {{< glossary_tooltip text="Kube-proxy" term_id="kube-proxy" >}} running in iptables mode or IPVS mode
39-
* Enable [Endpoint Slices](/docs/concepts/services-networking/endpoint-slices/)
31+
* Kubernetes v1.17 or later
32+
* Configure {{< glossary_tooltip text="kube-proxy" term_id="kube-proxy" >}} to run in iptables mode or IPVS mode
33+
34+
35+
<!-- steps -->
4036

4137
## Enable Service Topology
4238

43-
{{< feature-state for_k8s_version="v1.17" state="alpha" >}}
39+
{{< feature-state for_k8s_version="v1.21" state="deprecated" >}}
4440

45-
To enable service topology, enable the `ServiceTopology` and `EndpointSlice` feature gate for all Kubernetes components:
41+
To enable service topology, enable the `ServiceTopology`
42+
[feature gate](/docs/reference/command-line-tools-reference/feature-gates/) for all Kubernetes components:
4643

4744
```
48-
--feature-gates="ServiceTopology=true,EndpointSlice=true"
45+
--feature-gates="ServiceTopology=true`
4946
```
5047

51-
5248
## {{% heading "whatsnext" %}}
5349

54-
55-
* Read about the [Service Topology](/docs/concepts/services-networking/service-topology) concept
56-
* Read about [Endpoint Slices](/docs/concepts/services-networking/endpoint-slices)
50+
* Read about [Topology Aware Hints](/docs/concepts/services-networking/topology-aware-hints/), the replacement for the `topologyKeys` field.
51+
* Read about [EndpointSlices](/docs/concepts/services-networking/endpoint-slices/)
52+
* Read about the [Service Topology](/docs/concepts/services-networking/service-topology/) concept
5753
* Read [Connecting Applications with Services](/docs/concepts/services-networking/connect-applications-service/)
5854

5955

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

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -10,22 +10,23 @@ min-kubernetes-server-version: 1.21
1010
{{< feature-state for_k8s_version="v1.21" state="alpha" >}}
1111

1212
_Topology Aware Hints_ enable topology aware routing with topology hints
13-
included in EndpointSlices. This approach tries to keep traffic close to where
14-
it originated from. This can result in decreased costs and improved performance.
13+
included in {{< glossary_tooltip text="EndpointSlices" term_id="endpoint-slice" >}}.
14+
This approach tries to keep traffic close to where it originated from;
15+
you might do this to reduce costs, or to improve network performance.
1516

1617
## {{% heading "prerequisites" %}}
1718

1819
{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}}
1920

2021
The following prerequisite is needed in order to enable topology aware hints:
2122

22-
* {{< glossary_tooltip text="Kube-proxy" term_id="kube-proxy" >}} running in
23+
* Configure the {{< glossary_tooltip text="kube-proxy" term_id="kube-proxy" >}} to run in
2324
iptables mode or IPVS mode
2425
* Ensure that you have not disabled EndpointSlices
2526

2627
## Enable Topology Aware Hints
2728

28-
To enable service topology, enable the `TopologyAwareHints` [feature
29+
To enable service topology hints, enable the `TopologyAwareHints` [feature
2930
gate](docs/reference/command-line-tools-reference/feature-gates/) for the
3031
kube-apiserver, kube-controller-manager, and kube-proxy:
3132

0 commit comments

Comments
 (0)