tiproxy: add docs for label-based balance

tiproxy/tiproxy-configuration.md

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

tiproxy/tiproxy-load-balance.md

@@ -5,23 +5,78 @@ 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 通过该标签名查找 TiProxy 的 [`labels`](/tiproxy/tiproxy-configuration.md#labels) 配置和 TiDB server 上的 [`labels`](/tidb-configuration-file.md#labels) 配置，并优先将连接路由到与自身的标签值相同的 TiDB server 上。
+
+例如，应用有交易和 BI 两类业务，为了避免相互影响，可以如下配置集群：
+
+- TiProxy 上配置 [`balance.label-name`](/tiproxy/tiproxy-configuration.md#label-name) 为 `app`，表示将按照标签名 `app` 匹配 TiDB server，并将连接路由到相同标签值的 TiDB server 上。
+- 配置 2 台 TiProxy 实例，配置项 [`labels`](/tiproxy/tiproxy-configuration.md#labels) 分别加上 `"app"="Order"` 和 `"app"="BI"`。
+- 将 TiDB 实例分为 2 组，配置项 [`labels`](/tidb-configuration-file.md#labels) 分别加上 `"app"="Order"` 和 `"app"="BI"`。 
+- 配置 [Placement Rules](/configure-placement-rules.md) 或[资源管控](/tidb-resource-control.md) 以实现存储层的资源隔离。
+- 交易和 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 +154,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 +177,9 @@ TiProxy 通常根据 CPU 使用率来识别 TiDB server 的负载。该策略通
 
 TiProxy 支持通过配置项 [`policy`](/tiproxy/tiproxy-configuration.md#policy) 配置上述负载均衡策略的组合和优先级。
 
-- `resource`：资源优先策略，优先级顺序依次为基于状态、健康度、内存、CPU、地理位置、连接数的负载均衡。
-- `location`：地理优先策略，优先级顺序依次为基于状态、地理位置、健康度、内存、CPU、连接数的负载均衡。
-- `connection`：最小连接数策略，优先级顺序依次为基于状态、连接数的负载均衡。
+- `resource`：资源优先策略，优先级顺序依次为基于状态、标签、健康度、内存、CPU、地理位置、连接数的负载均衡。
+- `location`：地理优先策略，优先级顺序依次为基于状态、标签、地理位置、健康度、内存、CPU、连接数的负载均衡。
+- `connection`：最小连接数策略，优先级顺序依次为基于状态、标签、连接数的负载均衡。
 
 ## 资源