Skip to content

Commit

Permalink
Merge pull request envoyproxy#187 from webup/intro/arch/upstream/lb/s…
Browse files Browse the repository at this point in the history 
…ubsets

zh-translation: /intro/arch_overview/upstream/load_balancing/subsets.rst
  • Loading branch information
@scilla0531
scilla0531 authored Nov 27, 2020
2 parents c2c2124 + 433c08a commit 8f3b996
Showing 1 changed file with 35 additions and 76 deletions.
111 changes: 35 additions & 76 deletions docs/root/intro/arch_overview/upstream/load_balancing/subsets.rst
View file
Original file line number Diff line number Diff line change
@@ -1,76 +1,39 @@
.. _arch_overview_load_balancer_subsets:

Load Balancer Subsets
负载均衡器子集
---------------------

Envoy may be configured to divide hosts within an upstream cluster into subsets based on metadata
attached to the hosts. Routes may then specify the metadata that a host must match in order to be
selected by the load balancer, with the option of falling back to a predefined set of hosts,
including any host.

Subsets use the load balancer policy specified by the cluster. The original destination policy may
not be used with subsets because the upstream hosts are not known in advance. Subsets are compatible
with zone aware routing, but be aware that the use of subsets may easily violate the minimum hosts
condition described above.

If subsets are :ref:`configured <envoy_v3_api_field_config.cluster.v3.Cluster.lb_subset_config>` and a route
specifies no metadata or no subset matching the metadata exists, the subset load balancer initiates
its fallback policy. The default policy is ``NO_FALLBACK``, in which case the request fails as if
the cluster had no hosts. Conversely, the ``ANY_ENDPOINT`` fallback policy load balances across all
hosts in the cluster, without regard to host metadata. Finally, the ``DEFAULT_SUBSET`` causes
fallback to load balance among hosts that match a specific set of metadata. It is possible to
override fallback policy for specific subset selector.

Subsets must be predefined to allow the subset load balancer to efficiently select the correct
subset of hosts. Each definition is a set of keys, which translates to zero or more
subsets. Conceptually, each host that has a metadata value for all of the keys in a definition is
added to a subset specific to its key-value pairs. If no host has all the keys, no subsets result
from the definition. Multiple definitions may be provided, and a single host may appear in multiple
subsets if it matches multiple definitions.

During routing, the route's metadata match configuration is used to find a specific subset. If there
is a subset with the exact keys and values specified by the route, the subset is used for load
balancing. Otherwise, the fallback policy is used. The cluster's subset configuration must,
therefore, contain a definition that has the same keys as a given route in order for subset load
balancing to occur.

Subsets can be configured with only a single host in each subset, which can be used in use cases
similar to :ref:`Maglev <arch_overview_load_balancing_types_maglev>` or
:ref:`ring hash <arch_overview_load_balancing_types_ring_hash>`, such as load balancing based on a cookie,
but when it is important to select the same host even after new hosts are added to the cluster. Endpoint
configuration changes may use less CPU if :ref:`single_host_per_subset <envoy_v3_api_field_config.cluster.v3.Cluster.LbSubsetConfig.LbSubsetSelector.single_host_per_subset>`
is enabled.

Host metadata is only supported when hosts are defined using
:ref:`ClusterLoadAssignments <envoy_v3_api_msg_config.endpoint.v3.ClusterLoadAssignment>`. ClusterLoadAssignments are
available via EDS or the Cluster :ref:`load_assignment <envoy_v3_api_field_config.cluster.v3.Cluster.load_assignment>`
field. Host metadata for subset load balancing must be placed under the filter name ``"envoy.lb"``.
Similarly, route metadata match criteria use ``"envoy.lb"`` filter name. Host metadata may be
hierarchical (e.g., the value for a top-level key may be a structured value or list), but the
subset load balancer only compares top-level keys and values. Therefore when using structured
values, a route's match criteria will only match if an identical structured value appears in the
host's metadata.

Finally, note that subset load balancing is not available for the
:ref:`CLUSTER_PROVIDED <envoy_v3_api_enum_value_config.cluster.v3.Cluster.LbPolicy.CLUSTER_PROVIDED>` load balancer
policies.

Examples
Envoy 可被配置为根据主机所带的元数据将上游集群内的主机分为若干子集。然后，路由可以指定主机必须匹配的元数据，以便被负载平衡器选择，并可选择回退到预先设定的某些主机（包括任何主机）。

负载均衡器子集使用集群指定的负载均衡策略。由于事先不知道上游主机，所以子集可能无法使用原始目的地策略。子集与区域感知路由兼容，但要注意子集的使用很容易违反上述的最小主机匹配条件。

如果子集是 :ref:`已配置的 <envoy_v3_api_field_config.cluster.v3.Cluster.lb_subset_config>`，并且路由指定没有元数据或没有匹配元数据的子集存在，则负载均衡器子集启动其后备策略。默认策略是 ``NO_FALLBACK``，在这种情况下，请求会失败，就像集群没有主机一样。相反，``ANY_ENDPOINT`` 后备策略会在集群中的所有主机上进行负载均衡，而不考虑主机元数据。最后，``DEFAULT_SUBSET`` 后备策略会使负载均衡在符合特定元数据集的主机之间进行。通过特定的子集选择器配置，可以覆盖后备策略。

子集必须被预定义，以使负载均衡器子集能够有效地选择正确的主机子集。每个定义都是一组键，这就转化为零个或多个子集。从概念上讲，每台主机如果具有定义中所有键的元数据值，就会被添加到特定于其键值对的子集中。如果没有主机可以匹配到所有键，则该定义就不会产生子集。可以提供多个定义，如果一个主机与多个定义相匹配，它可以出现在多个子集中。

在路由过程中，路由的元数据匹配配置被用来寻找特定的子集。如果有一个子集与路由指定的键和值完全一致，则使用该子集进行负载均衡。否则，将使用后备策略。因此，集群的子集配置必须包含一个与给定路由具有相同键的定义，才能实现子集负载均衡。

子集可以被配置为每个子集中只有一台主机，这可以用于类似于 :ref:`Maglev <arch_overview_load_balancing_types_maglev>` 或 :ref:`哈希环 <arch_overview_load_balancing_types_ring_hash>` 的用例，例如基于 Cookie 的负载均衡，这类场景通常需要实现即使在新主机添加到集群后也要选择相同的主机。如果启用了 :ref:`single_host_per_subset <envoy_v3_api_field_config.cluster.v3.Cluster.LbSubsetConfig.LbSubsetSelector.single_host_per_subset>`，则端点配置更改可能会使用较少的 CPU。

只有在使用 :ref:`ClusterLoadAssignments <envoy_v3_api_msg_config.endpoint.v3.ClusterLoadAssignment>` 定义主机时，才支持主机元数据。ClusterLoadAssignments 可通过 EDS 或集群的 :ref:`load_assignment <envoy_v3_api_field_config.cluster.v3.Cluster.load_assignment>` 字段获得。用于子集负载均衡的主机元数据必须放在过滤器名称 ``"envoy.lb"`` 下。同样，路由元数据匹配条件使用 ``"envoy.lb"`` 过滤器名称。主机元数据可以是分层的（例如，顶层键的值可以是一个结构化的值或列表），但负载均衡器子集只比较顶层键和值。因此，当使用结构化值时，只有当主机的元数据中出现相同的结构化值时，路由的匹配条件才会匹配成功。

最后，需要注意的是，负载均衡器子集是无法使用 :ref:`CLUSTER_PROVIDED <envoy_v3_api_enum_value_config.cluster.v3.Cluster.LbPolicy.CLUSTER_PROVIDED>` 负载均衡器策略的。

示例
^^^^^^^^

We'll use simple metadata where all values are strings. Assume the following hosts are defined and
associated with a cluster:
我们将在示例中使用简单的元数据，所有的值都是字符串。假定在一个集群中有以下的主机：

====== ======================
Host Metadata
主机 元数据
====== ======================
host1 v: 1.0, stage: prod
host2 v: 1.0, stage: prod
host3 v: 1.1, stage: canary
host4 v: 1.2-pre, stage: dev
====== ======================

The cluster may enable subset load balancing like this:
集群可以像这样启用负载均衡器子集：

::

Expand All @@ -95,27 +58,23 @@ The cluster may enable subset load balancing like this:
- stage
fallback_policy: NO_FALLBACK

The following table describes some routes and the result of their application to the
cluster. Typically the match criteria would be used with routes matching specific aspects of the
request, such as the path or header information.
下表描述了一些路由和它们应用到集群的结果。通常，匹配标准将用于匹配请求的特定方面，如路径或请求头信息的路由。

====================== ============= ======================================================================
Match Criteria Balances Over Reason
匹配条件 选择目标 选择原因
====================== ============= ======================================================================
stage: canary host3 Subset of hosts selected
v: 1.2-pre, stage: dev host4 Subset of hosts selected
v: 1.0 host1, host2 Fallback: No subset selector for "v" alone
other: x host1, host2 Fallback: No subset selector for "other"
(none) host1, host2 Fallback: No subset requested
stage: test empty cluster As fallback policy is overridden per selector with "NO_FALLBACK" value
stage: canary host3 匹配到主机子集
v: 1.2-pre, stage: dev host4 匹配到主机子集
v: 1.0 host1, host2 后备：没有子集可以单独匹配键值 "v"
other: x host1, host2 后备：没有子集可以匹配到键值 "other"
(none) host1, host2 后备：没有子集匹配请求
stage: test 空集群 后备策略被覆盖为 "NO_FALLBACK"
====================== ============= ======================================================================

Metadata match criteria may also be specified on a route's weighted clusters. Metadata match
criteria from the selected weighted cluster are merged with and override the criteria from the
route:
元数据匹配条件也可以在路由的加权集群上指定。所选加权集群的元数据匹配条件整合并覆盖路由的匹配条件：

==================== =============================== ====================
Route Match Criteria Weighted Cluster Match Criteria Final Match Criteria
路由匹配条件 加权集群匹配条件 最终匹配条件
==================== =============================== ====================
stage: canary stage: prod stage: prod
v: 1.0 stage: prod v: 1.0, stage: prod
Expand All @@ -126,10 +85,10 @@ v: 1.0 (none) v: 1.0
==================== =============================== ====================


Example Host With Metadata
带元数据的主机示例
**************************

An EDS ``LbEndpoint`` with host metadata:
一个含有主机元数据的 EDS ``LbEndpoint``：

::

Expand All @@ -147,10 +106,10 @@ An EDS ``LbEndpoint`` with host metadata:
stage: 'prod'


Example Route With Metadata Criteria
带元数据匹配条件的路径示例
************************************

An RDS ``Route`` with metadata match criteria:
一个具备元数据匹配条件的 RDS ``Route``：

::

Expand Down

0 comments on commit 8f3b996

Please sign in to comment.