tiproxy: add basic document (#2477)

zh/TOC.md

@@ -22,6 +22,7 @@
     - [阿里云 ACK](deploy-on-alibaba-cloud.md)
   - [在 ARM64 机器上部署 TiDB 集群](deploy-cluster-on-arm64.md)
   - [部署 TiDB HTAP 存储引擎 TiFlash](deploy-tiflash.md)
+  - [部署 TiDB 负载均衡 TiProxy](deploy-tiproxy.md)
   - 跨多个 Kubernetes 集群部署 TiDB 集群
     - [构建多个网络互通的 AWS EKS 集群](build-multi-aws-eks.md)
     - [构建多个网络互通的 GKE 集群](build-multi-gcp-gke.md)

zh/configure-a-tidb-cluster.md

@@ -223,7 +223,7 @@ TiDB Operator 支持为 PD、TiDB、TiKV、TiCDC 挂载多块 PV，可以用于
 
 ### HostNetwork
 
-PD、TiKV、TiDB、TiFlash、TiCDC 及 Pump 支持配置 Pod 使用宿主机上的网络命名空间 [`HostNetwork`](https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/#pod-s-dns-policy)。可通过配置 `spec.hostNetwork: true` 为所有受支持的组件开启，或通过为特定组件配置 `hostNetwork: true` 为单个或多个组件开启。
+PD、TiKV、TiDB、TiFlash、TiProxy、TiCDC 及 Pump 支持配置 Pod 使用宿主机上的网络命名空间 [`HostNetwork`](https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/#pod-s-dns-policy)。可通过配置 `spec.hostNetwork: true` 为所有受支持的组件开启，或通过为特定组件配置 `hostNetwork: true` 为单个或多个组件开启。
 
 ### Discovery
 
@@ -251,6 +251,17 @@ spec:
 >
 > 如果 Kubernetes 集群节点个数少于 3 个，将会导致有一个 PD Pod 处于 Pending 状态，而 TiKV 和 TiDB Pod 也都不会被创建。Kubernetes 集群节点个数少于 3 个时，为了使 TiDB 集群能启动起来，可以将默认部署的 PD Pod 个数减小到 1 个。
 
+#### 部署 TiProxy
+
+部署方法与 PD 一致。此外，还需要修改 `spec.tiproxy` 来手动指定 TiProxy 组件的数量。
+
+```yaml
+  tiproxy:
+    baseImage: pingcap/tiproxy
+    replicas: 3
+    config:
+```
+
 #### 部署 TiFlash
 
 如果要在集群中开启 TiFlash，需要在 `${cluster_name}/tidb-cluster.yaml` 文件中配置 `spec.pd.config.replication.enable-placement-rules: true`，并配置 `spec.tiflash`：
@@ -310,7 +321,7 @@ TiFlash 支持挂载多个 PV，如果要为 TiFlash 配置多个 PV，可以在
 
 ### 配置 TiDB 组件
 
-本节介绍如何配置 TiDB/TiKV/PD/TiFlash/TiCDC 的配置选项。
+本节介绍如何配置 TiDB/TiKV/PD/TiProxy/TiFlash/TiCDC 的配置选项。
 
 #### 配置 TiDB 配置参数
 
@@ -368,6 +379,20 @@ spec:
 > - 为了兼容 `helm` 部署，如果你是通过 CR 文件部署 TiDB 集群，即使你不设置 Config 配置，也需要保证 `Config: {}` 的设置，从而避免 PD 组件无法正常启动。
 > - PD 部分配置项在首次启动成功后会持久化到 etcd 中且后续将以 etcd 中的配置为准。因此 PD 在首次启动后，这些配置项将无法再通过配置参数来进行修改，而需要使用 SQL、pd-ctl 或 PD server API 来动态进行修改。目前，[在线修改 PD 配置](https://docs.pingcap.com/zh/tidb/stable/dynamic-config#在线修改-pd-配置)文档中所列的配置项中，除 `log.level` 外，其他配置项在 PD 首次启动之后均不再支持通过配置参数进行修改。
 
+#### 配置 TiProxy 配置参数
+
+你可以通过 TidbCluster CR 的 `spec.tiproxy.config` 来配置 TiProxy 配置参数。
+
+```yaml
+spec:
+  tiproxy:
+    config: |
+      [log]
+      level = "info"
+```
+
+获取所有可以配置的 TiProxy 配置参数，请参考 [TiProxy 配置文档](https://docs.pingcap.com/zh/tidb/v7.6/tiproxy/tiproxy-configuration)。
+
 #### 配置 TiFlash 配置参数
 
 你可以通过 TidbCluster CR 的 `spec.tiflash.config` 来配置 TiFlash 配置参数。
@@ -617,6 +642,8 @@ spec:
 
 访问 [Kubernetes Service 文档](https://kubernetes.io/docs/concepts/services-networking/service/)，了解更多 Service 特性以及云平台 Load Balancer 支持。
 
+若指定了 TiProxy，也会自动创建 `tiproxy-api` 和 `tiproxy-sql` 服务供使用。
+
 ### IPv6 支持
 
 TiDB 自 v6.5.1 起支持使用 IPv6 地址进行所有网络连接。如果你使用 v1.4.3 或以上版本的 TiDB Operator 部署 TiDB，你可以通过配置 `spec.preferIPv6` 为 `ture` 来部署监听 IPv6 地址的 TiDB 集群。

zh/deploy-failures.md

@@ -41,6 +41,7 @@ Pod 处于 Pending 状态，通常都是资源不满足导致的，比如：
 * 使用持久化存储的 PD、TiKV、TiFlash、Pump、Monitor、Backup、Restore Pod 使用的 PVC 的 StorageClass 不存在或 PV 不足
 * Kubernetes 集群中没有节点能满足 Pod 申请的 CPU 或内存
 * PD 或者 TiKV Replicas 数量和集群内节点数量不满足 tidb-scheduler 高可用调度策略
+* TiDB、TiProxy 等组件使用的证书没有配置
 
 此时，可以通过 `kubectl describe pod` 命令查看 Pending 的具体原因：
 

zh/deploy-on-general-kubernetes.md

@@ -53,6 +53,7 @@ aliases: ['/docs-cn/tidb-in-kubernetes/dev/deploy-on-general-kubernetes/','/zh/t
     pingcap/tidb-binlog:v7.5.0
     pingcap/ticdc:v7.5.0
     pingcap/tiflash:v7.5.0
+    pingcap/tiproxy:latest
     pingcap/tidb-monitor-reloader:v1.0.1
     pingcap/tidb-monitor-initializer:v7.5.0
     grafana/grafana:7.5.11
@@ -71,6 +72,7 @@ aliases: ['/docs-cn/tidb-in-kubernetes/dev/deploy-on-general-kubernetes/','/zh/t
     docker pull pingcap/tidb-binlog:v7.5.0
     docker pull pingcap/ticdc:v7.5.0
     docker pull pingcap/tiflash:v7.5.0
+    docker pull pingcap/tiproxy:latest
     docker pull pingcap/tidb-monitor-reloader:v1.0.1
     docker pull pingcap/tidb-monitor-initializer:v7.5.0
     docker pull grafana/grafana:7.5.11
@@ -82,6 +84,7 @@ aliases: ['/docs-cn/tidb-in-kubernetes/dev/deploy-on-general-kubernetes/','/zh/t
     docker save -o tidb-v7.5.0.tar pingcap/tidb:v7.5.0
     docker save -o tidb-binlog-v7.5.0.tar pingcap/tidb-binlog:v7.5.0
     docker save -o ticdc-v7.5.0.tar pingcap/ticdc:v7.5.0
+    docker save -o tiproxy-latest.tar pingcap/tiproxy:latest
     docker save -o tiflash-v7.5.0.tar pingcap/tiflash:v7.5.0
     docker save -o tidb-monitor-reloader-v1.0.1.tar pingcap/tidb-monitor-reloader:v1.0.1
     docker save -o tidb-monitor-initializer-v7.5.0.tar pingcap/tidb-monitor-initializer:v7.5.0
@@ -100,6 +103,7 @@ aliases: ['/docs-cn/tidb-in-kubernetes/dev/deploy-on-general-kubernetes/','/zh/t
     docker load -i tidb-v7.5.0.tar
     docker load -i tidb-binlog-v7.5.0.tar
     docker load -i ticdc-v7.5.0.tar
+    docker load -i tiproxy-latest.tar
     docker load -i tiflash-v7.5.0.tar
     docker load -i tidb-monitor-reloader-v1.0.1.tar
     docker load -i tidb-monitor-initializer-v7.5.0.tar

zh/deploy-tidb-cluster-across-multiple-kubernetes.md

@@ -509,19 +509,20 @@ EOF
 
 2. 以步骤 1 为例，按顺序进行如下升级操作：
 
-   1. 如果集群中部署了 TiFlash，为所有部署了 TiFlash 的 Kubernetes 集群升级 TiFlash 版本。
-   2. 升级所有 Kubernetes 集群的 TiKV 版本。
-   3. 如果集群中部署了 Pump，为所有部署了 Pump 的 Kubernetes 集群升级 Pump 版本。
-   4. 升级所有 Kubernetes 集群的 TiDB 版本。
-   5. 如果集群中部署了 TiCDC，为所有部署了 TiCDC 的 Kubernetes 集群升级 TiCDC 版本。
+    1. 如果集群中部署了 TiProxy，为所有部署了 TiProxy 的 Kubernetes 集群升级 TiProxy 版本。
+    2. 如果集群中部署了 TiFlash，为所有部署了 TiFlash 的 Kubernetes 集群升级 TiFlash 版本。
+    3. 升级所有 Kubernetes 集群的 TiKV 版本。
+    4. 如果集群中部署了 Pump，为所有部署了 Pump 的 Kubernetes 集群升级 Pump 版本。
+    5. 升级所有 Kubernetes 集群的 TiDB 版本。
+    6. 如果集群中部署了 TiCDC，为所有部署了 TiCDC 的 Kubernetes 集群升级 TiCDC 版本。
 
 ## 退出和回收已加入的 TidbCluster
 
 当你需要让一个集群从所加入的跨 Kubernetes 部署的 TiDB 集群退出并回收资源时，可以通过缩容流程来实现上述需求。在此场景下，需要满足缩容的一些限制，限制如下：
 
 - 缩容后，集群中 TiKV 副本数应大于 PD 中设置的 `max-replicas` 数量，默认情况下 TiKV 副本数量需要大于 3。
 
-以上面文档创建的第二个 TidbCluster 为例，先将 PD、TiKV、TiDB 的副本数设置为 0，如果开启了 TiFlash、TiCDC、Pump 等其他组件，也请一并将其副本数设为 0：
+以上面文档创建的第二个 TidbCluster 为例，先将 PD、TiKV、TiDB 的副本数设置为 0，如果开启了 TiFlash、TiCDC、TiProxy、Pump 等其他组件，也请一并将其副本数设为 `0`：
 
 {{< copyable "shell-regular" >}}
 
@@ -643,4 +644,4 @@ kubectl patch tidbcluster cluster1 --type merge -p '{"spec":{"acrossK8s": true}}
 
 ## 跨多个 Kubernetes 集群部署的 TiDB 集群监控
 
-请参阅[跨多个 Kubernetes 集群监控 TiDB 集群](deploy-tidb-monitor-across-multiple-kubernetes.md)
+请参阅[跨多个 Kubernetes 集群监控 TiDB 集群](deploy-tidb-monitor-across-multiple-kubernetes.md)。

zh/deploy-tiproxy.md

@@ -0,0 +1,94 @@
+---
+title: 为已有 TiDB 集群部署负载均衡 TiProxy
+summary: 了解如何在 Kubernetes 上为已有 TiDB 集群部署负载均衡 TiProxy。
+---
+
+# 为已有 TiDB 集群部署负载均衡 TiProxy
+
+本文介绍在 Kubernetes 上如何为已有的 TiDB 集群部署或删除 TiDB 负载均衡 [TiProxy](https://docs.pingcap.com/zh/tidb/v7.6/tiproxy/tiproxy-overview)。TiProxy 放置在客户端和 TiDB server 之间，为 TiDB 提供负载均衡、连接保持、服务发现等功能。
+
+> **注意：**
+>
+> 如果尚未部署 TiDB 集群, 你可以在[配置 TiDB 集群](configure-a-tidb-cluster.md)时增加 TiProxy 相关配置，然后[部署 TiDB 集群](deploy-on-general-kubernetes.md)，因此无需参考本文。
+
+## 部署 TiProxy
+
+如果你需要在现有的 TiDB 集群上部署 TiProxy 组件，请进行以下操作：
+
+> **注意：**
+>
+> 如果服务器没有外网，请参考[部署 TiDB 集群](deploy-on-general-kubernetes.md#部署-tidb-集群)在有外网的机器上将 `pingcap/tiproxy` Docker 镜像下载下来并上传到服务器上, 然后使用 `docker load` 将 Docker 镜像安装到服务器上。
+
+1. 编辑 TidbCluster Custom Resource (CR)：
+
+    ``` shell
+    kubectl edit tc ${cluster_name} -n ${namespace}
+    ```
+
+2. 按照如下示例增加 TiProxy 配置：
+
+    ```yaml
+    spec:
+      tiproxy:
+        baseImage: pingcap/tiproxy
+        replicas: 3
+    ```
+
+3. 配置 TidbCluster CR 中 `spec.tiproxy.config` 的相关参数。例如：
+
+    ```yaml
+    spec:
+      tiproxy:
+        config:
+          config: |
+            [log]
+            level = "info"
+    ```
+
+    要获取更多可配置的 TiProxy 配置参数，请参考 [TiProxy 配置文档](https://docs.pingcap.com/zh/tidb/v7.6/tiproxy/tiproxy-configuration)。
+
+TiProxy 启动后，可通过以下命令找到对应的 `tiproxy-sql` 负载均衡服务。
+
+``` shell
+kubectl get svc -n ${namespace}
+```
+
+## 移除 TiProxy
+
+如果你的 TiDB 集群不再需要 TiProxy，执行以下操作移除。
+
+1. 执行以下命令修改 `spec.tiproxy.replicas` 为 `0` 来移除 TiProxy Pod。
+
+    ```shell
+    kubectl patch tidbcluster ${cluster_name} -n ${namespace} --type merge -p '{"spec":{"tiproxy":{"replicas": 0}}}'
+    ```
+
+2. 检查 TiProxy Pod 状态。
+
+    ```shell
+    kubectl get pod -n ${namespace} -l app.kubernetes.io/component=tiproxy,app.kubernetes.io/instance=${cluster_name}
+    ```
+
+    如果输出为空，则表示 TiProxy 集群的 Pod 已经被成功删除。
+
+3. 删除 TiProxy StatefulSet。
+
+    1. 使用以下命令修改 TiDB Cluster CR，删除 `spec.tiproxy` 字段。
+
+        ```shell
+        kubectl patch tidbcluster ${cluster_name} -n ${namespace} --type json -p '[{"op":"remove", "path":"/spec/tiproxy"}]'
+        ```
+
+    2. 使用以下命令删除 TiProxy StatefulSet：
+
+        ```shell
+        kubectl delete statefulsets -n ${namespace} -l app.kubernetes.io/component=tiproxy,app.kubernetes.io/instance=${cluster_name}
+        ```
+
+    3. 执行以下命令，检查是否已经成功删除 TiProxy 集群的 StatefulSet：
+
+        ```shell
+        kubectl get sts -n ${namespace} -l app.kubernetes.io/component=tiproxy,app.kubernetes.io/instance=${cluster_name}
+        ```
+
+        如果输出为空，则表示 TiProxy 集群的 StatefulSet 已经被成功删除。

zh/enable-tls-between-components.md

@@ -9,7 +9,7 @@ aliases: ['/docs-cn/tidb-in-kubernetes/dev/enable-tls-between-components/']
 本文主要描述了在 Kubernetes 上如何为 TiDB 集群组件间开启 TLS。TiDB Operator 从 v1.1 开始已经支持为 Kubernetes 上 TiDB 集群组件间开启 TLS。开启步骤为：
 
 1. 为即将被创建的 TiDB 集群的每个组件生成证书：
-    - 为 PD/TiKV/TiDB/Pump/Drainer/TiFlash/TiKV Importer/TiDB Lightning 组件分别创建一套 Server 端证书，保存为 Kubernetes Secret 对象：`${cluster_name}-${component_name}-cluster-secret`
+    - 为 PD/TiKV/TiDB/Pump/Drainer/TiFlash/TiProxy/TiKV Importer/TiDB Lightning 组件分别创建一套 Server 端证书，保存为 Kubernetes Secret 对象：`${cluster_name}-${component_name}-cluster-secret`
     - 为它们的各种客户端创建一套共用的 Client 端证书，保存为 Kubernetes Secret 对象：`${cluster_name}-cluster-client-secret`
 
     > **注意：**
@@ -401,6 +401,43 @@ aliases: ['/docs-cn/tidb-in-kubernetes/dev/enable-tls-between-components/']
         cfssl gencert -ca=ca.pem -ca-key=ca-key.pem -config=ca-config.json -profile=internal ticdc-server.json | cfssljson -bare ticdc-server
         ```
 
+    - TiProxy Server 端证书
+
+        首先生成默认的 `tiproxy-server.json` 文件：
+
+        ``` shell
+        cfssl print-defaults csr > tiproxy-server.json
+        ```
+
+        然后编辑这个文件，修改 `CN` 和 `hosts` 属性：
+
+        ``` json
+        ...
+            "CN": "TiDB",
+            "hosts": [
+              "127.0.0.1",
+              "::1",
+              "${cluster_name}-tiproxy",
+              "${cluster_name}-tiproxy.${namespace}",
+              "${cluster_name}-tiproxy.${namespace}.svc",
+              "${cluster_name}-tiproxy-peer",
+              "${cluster_name}-tiproxy-peer.${namespace}",
+              "${cluster_name}-tiproxy-peer.${namespace}.svc",
+              "*.${cluster_name}-tiproxy-peer",
+              "*.${cluster_name}-tiproxy-peer.${namespace}",
+              "*.${cluster_name}-tiproxy-peer.${namespace}.svc"
+            ],
+        ...
+        ```
+
+        其中 `${cluster_name}` 为集群的名字，`${namespace}` 为 TiDB 集群部署的命名空间，你也可以添加自定义 `hosts`。
+
+        最后生成 TiProxy Server 端证书：
+
+        ``` shell
+        cfssl gencert -ca=ca.pem -ca-key=ca-key.pem -config=ca-config.json -profile=internal tiproxy-server.json | cfssljson -bare tiproxy-server
+        ```
+
     - TiFlash Server 端证书
 
         首先生成默认的 `tiflash-server.json` 文件：
@@ -596,6 +633,12 @@ aliases: ['/docs-cn/tidb-in-kubernetes/dev/enable-tls-between-components/']
     kubectl create secret generic ${cluster_name}-ticdc-cluster-secret --namespace=${namespace} --from-file=tls.crt=ticdc-server.pem --from-file=tls.key=ticdc-server-key.pem --from-file=ca.crt=ca.pem
     ```
 
+    TiProxy 集群证书 Secret：
+
+    ``` shell
+    kubectl create secret generic ${cluster_name}-tiproxy-cluster-secret --namespace=${namespace} --from-file=tls.crt=tiproxy-server.pem --from-file=tls.key=tiproxy-server-key.pem --from-file=ca.crt=ca.pem
+    ```
+
     TiFlash 集群证书 Secret：
 
     {{< copyable "shell-regular" >}}

zh/faq.md

@@ -135,7 +135,7 @@ PD 和 TiKV 使用 [Raft 一致性算法](https://raft.github.io/)将存储的
 
 * 升级中
 * 缩扩容中
-* PD、TiDB、TiKV、TiFlash 任一 Pod 状态不是 Ready
+* PD、TiDB、TiKV、TiFlash、TiProxy 任一 Pod 状态不是 Ready
 
 要判断 TiDB 集群是否真正不可用，你可以尝试连接 TiDB。如果无法连接成功，说明 TiDB 集群真正不可用。
 

zh/modify-tidb-configuration.md

@@ -13,7 +13,7 @@ TiDB 集群自身支持通过 SQL 对 TiDB、TiKV、PD 等组件进行[在线配
 
 对于 TiDB 和 TiKV，如果通过 SQL 进行[在线配置变更](https://docs.pingcap.com/zh/tidb/stable/dynamic-config)，在升级或者重启后，配置项会被 TidbCluster CR 中的配置项覆盖，导致在线变更的配置失效。因此，如果需要持久化修改配置，你需要在 TidbCluster CR 中直接修改配置项。
 
-对于 TiFlash、TiCDC 和 Pump，目前只能通过在 TidbCluster CR 中修改配置项。
+对于 TiFlash、TiProxy、TiCDC 和 Pump，目前只能通过在 TidbCluster CR 中修改配置项。
 
 在 TidbCluster CR 中修改配置项的步骤如下：
 
@@ -42,3 +42,7 @@ TiDB 集群自身支持通过 SQL 对 TiDB、TiKV、PD 等组件进行[在线配
 PD 中[支持在线修改的配置项](https://docs.pingcap.com/zh/tidb/stable/dynamic-config#在线修改-pd-配置)里，除 `log.level` 外，其他配置项在 PD 首次启动之后均不再支持通过 TidbCluster CR 进行修改。
 
 对于部署在 Kubernetes 中的 TiDB 集群，如需修改 PD 配置参数，需要使用 [SQL](https://docs.pingcap.com/zh/tidb/stable/dynamic-config/#在线修改-pd-配置)、[pd-ctl](https://docs.pingcap.com/tidb/stable/pd-control#config-show--set-option-value--placement-rules) 或 PD server API 来动态进行修改。
+
+## 修改 TiProxy 组件配置
+
+修改 TiProxy 组件的配置永远不会重启 Pod。如果你想要重启 Pod，需要手动杀死 Pod，或更改 Pod 镜像等配置，来手动触发重启。

zh/renew-tls-certificate.md

@@ -67,7 +67,7 @@ summary: 介绍如何更新和替换 TiDB 组件间的 TLS 证书。
 
     > **注意：**
     >
-    > 上述示例命令中仅更新了 PD、TiKV、TiDB 的组件间 Server 端 CA 证书与 Client 端 CA 证书，如需更新其他如 TiCDC、TiFlash 等的 Server 端 CA 证书，可使用类似命令进行更新。
+    > 上述示例命令中仅更新了 PD、TiKV、TiDB 的组件间 Server 端 CA 证书与 Client 端 CA 证书，如需更新其他如 TiCDC、TiFlash、TiProxy 等的 Server 端 CA 证书，可使用类似命令进行更新。
 
 5. 参考[滚动重启 TiDB 集群](restart-a-tidb-cluster.md)对需要加载组合 CA 证书的组件进行滚动重启。
 
@@ -110,7 +110,7 @@ summary: 介绍如何更新和替换 TiDB 组件间的 TLS 证书。
 
     > **注意：**
     >
-    > 上述示例命令中仅更新了 PD、TiKV、TiDB 的组件间 Server 端证书与 Client 端证书，如需更新其他如 TiCDC、TiFlash 等的 Server 端证书，可使用类似命令进行更新。
+    > 上述示例命令中仅更新了 PD、TiKV、TiDB 的组件间 Server 端证书与 Client 端证书，如需更新其他如 TiCDC、TiFlash、TiProxy 等的 Server 端证书，可使用类似命令进行更新。
 
 3. 参考[滚动重启 TiDB 集群](restart-a-tidb-cluster.md)对需要加载新证书的组件进行滚动重启。