whentimeslows/website
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request #27390 from sftim/20210403_tidy_service_endpoints_docs_1.21

Browse Source 
Tidy docs about EndpointSlice & related features
This commit is contained in:
Kubernetes Prow Robot
2021-04-05 08:07:13 -07:00
committed by GitHub
parent a2f0abd847 c9ca131355
commit 029c885a1b
6 changed files with 106 additions and 105 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/en/docs/concepts/services-networking/endpoint-slices.md
+1 -1
View File
@@ -3,7 +3,7 @@ reviewers:
- freehan
title: EndpointSlices
content_type: concept
weight: 35
weight: 45
---
content/en/docs/concepts/services-networking/service-topology.md
+23 -30
View File
@@ -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
+22 -15
View File
@@ -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
+33 -29
View File
@@ -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
+22 -26
View File
@@ -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.
_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.
## {{% heading "prerequisites" %}}
{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}}
<!-- steps -->
## Introduction
_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.
## Prerequisites
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
+5 -4
View File
@@ -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: