tiproxy: add docs for label-based balance (#18914) (#18972)

tiproxy/tiproxy-configuration.md

@@ -113,6 +113,13 @@ HTTP 网关的配置。
 
 TiProxy 负载均衡策略的配置。
 
+#### `label-name`
+
++ 默认值：`""`
++ 支持热加载：是
++ 指定用于[基于标签的负载均衡](/tiproxy/tiproxy-load-balance.md#基于标签的负载均衡)的标签名。TiProxy 根据该标签名匹配 TiDB server 的标签值，并优先将请求路由到与自身具有相同标签值的 TiDB server。
++ `label-name` 的默认值为空字符串，表示不使用基于标签的负载均衡。要启用该负载均衡策略，需要将此配置项设置为非空字符串，并配置 TiProxy 的 [`labels`](#labels) 和 TiDB 的 [`labels`](/tidb-configuration-file.md#labels) 配置项。有关详细信息，请参阅[基于标签的负载均衡](/tiproxy/tiproxy-load-balance.md#基于标签的负载均衡)。
+
 #### `policy`
 
 + 默认值：`resource`

tiproxy/tiproxy-grafana.md

@@ -59,6 +59,7 @@ TiProxy 有四个面板组。这些面板上的指标表示 TiProxy 的当前状
 - Session Migration Duration：会话迁移的平均、P95、P99 时长。
 - Session Migration Reasons：每分钟发生的会话迁移数，以及迁移的原因。原因包括：
     - `status`：TiProxy 进行了[基于状态的负载均衡](/tiproxy/tiproxy-load-balance.md#基于状态的负载均衡)
+    - `label`：TiProxy 进行了[基于标签的负载均衡](/tiproxy/tiproxy-load-balance.md#基于标签的负载均衡)
     - `health`：TiProxy 进行了[基于健康度的负载均衡](/tiproxy/tiproxy-load-balance.md#基于健康度的负载均衡)
     - `memory`：TiProxy 进行了[基于内存的负载均衡](/tiproxy/tiproxy-load-balance.md#基于内存的负载均衡)
     - `cpu`：TiProxy 进行了[基于 CPU 的负载均衡](/tiproxy/tiproxy-load-balance.md#基于-cpu-的负载均衡)

tiproxy/tiproxy-load-balance.md

@@ -5,23 +5,86 @@ summary: 介绍 TiProxy 的负载均衡策略及其适用场景。
 
 # TiProxy 负载均衡策略
 
-在 TiProxy v1.0.0 中，TiProxy 仅支持基于 TiDB server 状态和连接数的负载均衡策略。从 v1.1.0 开始，TiProxy 新增了四种可独立配置的负载均衡策略：基于健康度、内存、CPU 和地理位置。
+在 TiProxy v1.0.0 中，TiProxy 仅支持基于 TiDB server 状态和连接数的负载均衡策略。从 v1.1.0 开始，TiProxy 新增了 5 种负载均衡策略：基于标签、健康度、内存、CPU 和地理位置。
 
-TiProxy 默认启用所有策略，优先级从高到低依次为：
+默认配置下，这些策略的优先级从高到低依次为：
 
 1. 基于状态的负载均衡：当某个 TiDB server 正在关闭时，TiProxy 将连接从该 TiDB server 迁移到在线的 TiDB server。
-2. 基于健康度的负载均衡：当某个 TiDB server 的健康度异常时，TiProxy 将连接从该 TiDB server 迁移到健康度正常的 TiDB server。
-3. 基于内存的负载均衡：当某个 TiDB server 存在 Out of Memory (OOM) 风险时，TiProxy 将连接从该 TiDB server 迁移到内存使用量较低的 TiDB server。
-4. 基于 CPU 的负载均衡：当某个 TiDB server 的 CPU 使用率远高于其他 TiDB server 时，TiProxy 将连接从该 TiDB server 迁移到 CPU 使用率较低的 TiDB server。
-5. 基于地理位置的负载均衡：优先将请求路由到地理位置上距离 TiProxy 较近的 TiDB server。
-6. 基于连接数的负载均衡：当某个 TiDB server 的连接数远高于其他 TiDB server 时，TiProxy 将连接从该 TiDB server 迁移到连接数较少的 TiDB server。
+2. 基于标签的负载均衡：优先将请求路由到与 TiProxy 实例自身具有相同标签的 TiDB server，以实现计算层的资源隔离。
+3. 基于健康度的负载均衡：当某个 TiDB server 的健康度异常时，TiProxy 将连接从该 TiDB server 迁移到健康度正常的 TiDB server。
+4. 基于内存的负载均衡：当某个 TiDB server 存在 Out of Memory (OOM) 风险时，TiProxy 将连接从该 TiDB server 迁移到内存使用量较低的 TiDB server。
+5. 基于 CPU 的负载均衡：当某个 TiDB server 的 CPU 使用率远高于其他 TiDB server 时，TiProxy 将连接从该 TiDB server 迁移到 CPU 使用率较低的 TiDB server。
+6. 基于地理位置的负载均衡：优先将请求路由到地理位置上距离 TiProxy 较近的 TiDB server。
+7. 基于连接数的负载均衡：当某个 TiDB server 的连接数远高于其他 TiDB server 时，TiProxy 将连接从该 TiDB server 迁移到连接数较少的 TiDB server。
 
 如需调整负载均衡策略的优先级，请参考[负载均衡策略配置](#负载均衡策略配置)。
 
 ## 基于状态的负载均衡
 
 TiProxy 定时通过 SQL 端口和状态端口检查 TiDB 是否已下线或正在关闭。
 
+## 基于标签的负载均衡
+
+基于标签的负载均衡优先将连接路由到与 TiProxy 自身具有相同标签的 TiDB server 上，从而实现计算层的资源隔离。该策略默认关闭，仅当你的业务需要隔离计算层的资源时才需要启用。
+
+要启用基于标签的负载均衡，你需要：
+
+- 通过 [`balance.label-name`](/tiproxy/tiproxy-configuration.md#label-name) 指定用于匹配的标签名
+- 配置 TiProxy 配置项 [`labels`](/tiproxy/tiproxy-configuration.md#labels)
+- 配置 TiDB server 配置项 [`labels`](/tidb-configuration-file.md#labels)
+
+配置完成后，TiProxy 会根据 `balance.label-name` 指定的标签名查找相应的配置，并将连接路由到标签值相同的 TiDB server。
+
+例如，若应用包含交易和 BI 两类业务，为了避免相互影响，可以按照如下方式配置集群：
+
+1. 在 TiProxy 上配置 [`balance.label-name`](/tiproxy/tiproxy-configuration.md#label-name) 为 `"app"`，表示将按照标签名 `"app"` 匹配 TiDB server，并将连接路由到相同标签值的 TiDB server 上。
+2. 配置 2 台 TiProxy 实例，分别为配置项 [`labels`](/tiproxy/tiproxy-configuration.md#labels) 加上 `"app"="Order"` 和 `"app"="BI"`。
+3. 将 TiDB 实例分为 2 组，分别为配置项 [`labels`](/tidb-configuration-file.md#labels) 加上 `"app"="Order"` 和 `"app"="BI"`。 
+4. 如果需要同时隔离存储层的资源，可配置 [Placement Rules](/configure-placement-rules.md) 或[资源管控](/tidb-resource-control.md)。
+5. 交易和 BI 业务的客户端分别连接到 2 台 TiProxy 的地址。
+
+<img src="https://download.pingcap.com/images/docs-cn/tiproxy/tiproxy-balance-label.png" alt="基于标签的负载均衡" width="600" />
+
+上述拓扑图的配置示例如下：
+
+```yaml
+component_versions:
+  tiproxy: "v1.1.0"
+server_configs:
+  tiproxy:
+    balance.label-name: "app"
+  tidb:
+    graceful-wait-before-shutdown: 15
+tiproxy_servers:
+  - host: tiproxy-host-1
+    config:
+      labels: {app: "Order"}
+  - host: tiproxy-host-2
+    config:
+      labels: {app: "BI"}
+tidb_servers:
+  - host: tidb-host-1
+    config:
+      labels: {app: "Order"}
+  - host: tidb-host-2
+    config:
+      labels: {app: "Order"}
+  - host: tidb-host-3
+    config:
+      labels: {app: "BI"}
+  - host: tidb-host-4
+    config:
+      labels: {app: "BI"}
+tikv_servers:
+  - host: tikv-host-1
+  - host: tikv-host-2
+  - host: tikv-host-3
+pd_servers:
+  - host: pd-host-1
+  - host: pd-host-2
+  - host: pd-host-3
+```
+
 ## 基于健康度的负载均衡
 
 TiProxy 查询 TiDB server 的错误数来判断 TiDB server 的健康度，当某个 TiDB server 的健康度异常而其他 TiDB server 正常时，TiProxy 将该 TiDB server 的连接迁移到其他 TiDB server 上，实现自动故障转移。
@@ -99,11 +162,12 @@ tidb_servers:
         zone: west
 tikv_servers:
   - host: tikv-host-1
-    port: 20160
   - host: tikv-host-2
-    port: 20160
   - host: tikv-host-3
-    port: 20160
+pd_servers:
+  - host: pd-host-1
+  - host: pd-host-2
+  - host: pd-host-3
 ```
 
 在以上配置中，`tiproxy-host-1` 与 `tidb-host-1` 的 `zone` 配置相同，因此 `tiproxy-host-1` 上的 TiProxy 会优先将请求路由到 `tidb-host-1` 上的 TiDB server。同理，`tiproxy-host-2` 上的 TiProxy 会优先将请求路由到 `tidb-host-2` 上的 TiDB server。
@@ -121,9 +185,9 @@ TiProxy 通常根据 CPU 使用率来识别 TiDB server 的负载。该策略通
 
 TiProxy 支持通过配置项 [`policy`](/tiproxy/tiproxy-configuration.md#policy) 配置上述负载均衡策略的组合和优先级。
 
-- `resource`：资源优先策略，优先级顺序依次为基于状态、健康度、内存、CPU、地理位置、连接数的负载均衡。
-- `location`：地理优先策略，优先级顺序依次为基于状态、地理位置、健康度、内存、CPU、连接数的负载均衡。
-- `connection`：最小连接数策略，优先级顺序依次为基于状态、连接数的负载均衡。
+- `resource`：资源优先策略，优先级顺序依次为基于状态、标签、健康度、内存、CPU、地理位置、连接数的负载均衡。
+- `location`：地理优先策略，优先级顺序依次为基于状态、标签、地理位置、健康度、内存、CPU、连接数的负载均衡。
+- `connection`：最小连接数策略，优先级顺序依次为基于状态、标签、连接数的负载均衡。
 
 ## 资源