Skip to content

Commit

Permalink
tiproxy: add basic document
Browse files Browse the repository at this point in the history
Signed-off-by: xhe <[email protected]>
  • Loading branch information
xhebox committed Dec 12, 2023
1 parent 638db37 commit f4fdf83
Show file tree
Hide file tree
Showing 12 changed files with 108 additions and 18 deletions.
30 changes: 28 additions & 2 deletions zh/configure-a-tidb-cluster.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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`:
Expand Down Expand Up @@ -310,7 +321,7 @@ TiFlash 支持挂载多个 PV,如果要为 TiFlash 配置多个 PV,可以在

### 配置 TiDB 组件

本节介绍如何配置 TiDB/TiKV/PD/TiFlash/TiCDC 的配置选项。
本节介绍如何配置 TiDB/TiKV/PD/TiProxy/TiFlash/TiCDC 的配置选项。

#### 配置 TiDB 配置参数

Expand Down Expand Up @@ -368,6 +379,18 @@ 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"
```

#### 配置 TiFlash 配置参数

你可以通过 TidbCluster CR 的 `spec.tiflash.config` 来配置 TiFlash 配置参数。
Expand Down Expand Up @@ -601,6 +624,7 @@ NodePort 有两种模式:

- `externalTrafficPolicy=Local`:只有运行 TiDB 的机器会分配 NodePort 端口,用于访问本地的 TiDB 实例


#### LoadBalancer

若运行在有 LoadBalancer 的环境,比如 Google Cloud、AWS 平台,建议使用云平台的 LoadBalancer 特性。
Expand All @@ -617,6 +641,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 集群。
Expand Down
4 changes: 4 additions & 0 deletions zh/deploy-cluster-on-arm64.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,10 @@ summary: 本文档介绍如何在 ARM64 机器上部署 TiDB 集群
tiflash:
baseImage: pingcap/tiflash-arm64
# ...
tiproxy:
baseImage: pingcap/tiflash
# no need for -arm64
# ...
```

## 初始化 TiDB 集群
Expand Down
1 change: 1 addition & 0 deletions zh/deploy-failures.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 的具体原因:

Expand Down
4 changes: 4 additions & 0 deletions zh/deploy-on-general-kubernetes.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down
15 changes: 8 additions & 7 deletions zh/deploy-tidb-cluster-across-multiple-kubernetes.md
Original file line number Diff line number Diff line change
Expand Up @@ -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" >}}

Expand Down Expand Up @@ -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)
51 changes: 50 additions & 1 deletion zh/enable-tls-between-components.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`

> **注意:**
Expand Down Expand Up @@ -401,6 +401,47 @@ 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` 文件:
{{< copyable "shell-regular" >}}
``` 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 端证书:
{{< copyable "shell-regular" >}}
``` 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` 文件:
Expand Down Expand Up @@ -596,6 +637,14 @@ 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:
{{< copyable "shell-regular" >}}
``` 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" >}}
Expand Down
2 changes: 1 addition & 1 deletion zh/faq.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 集群真正不可用。

Expand Down
6 changes: 5 additions & 1 deletion zh/modify-tidb-configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 中修改配置项的步骤如下:

Expand Down Expand Up @@ -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 镜像等配置,来手动触发重启。
4 changes: 2 additions & 2 deletions zh/renew-tls-certificate.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 证书的组件进行滚动重启。

Expand Down Expand Up @@ -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)对需要加载新证书的组件进行滚动重启。

Expand Down
6 changes: 3 additions & 3 deletions zh/scale-a-tidb-cluster.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,9 +15,9 @@ TiDB 水平扩缩容操作指的是通过增加或减少 Pod 的数量,来达
* 如果要进行扩容操作,可将某个组件的 `replicas`**调大**。扩容操作会按照 Pod 编号由小到大增加组件 Pod,直到 Pod 数量与 `replicas` 值相等。
* 如果要进行缩容操作,可将某个组件的 `replicas`**调小**。缩容操作会按照 Pod 编号由大到小删除组件 Pod,直到 Pod 数量与 `replicas` 值相等。

### 水平扩缩容 PD、TiKV、TiDB
### 水平扩缩容 PD、TiKV、TiDB、TiProxy

如果要对 PD、TiKV、TiDB 进行水平扩缩容,可以使用 kubectl 修改集群所对应的 `TidbCluster` 对象中的 `spec.pd.replicas``spec.tikv.replicas``spec.tidb.replicas` 至期望值。
如果要对 PD、TiKV、TiDB、TiProxy 进行水平扩缩容,可以使用 kubectl 修改集群所对应的 `TidbCluster` 对象中的 `spec.pd.replicas``spec.tikv.replicas``spec.tidb.replicas``spec.tiproxy.replicas` 至期望值。

1. 按需修改 TiDB 集群组件的 `replicas` 值。例如,执行以下命令可将 PD 的 `replicas` 值设置为 3:

Expand Down Expand Up @@ -158,7 +158,7 @@ watch kubectl -n ${namespace} get pod -o wide

本小节介绍如何对 PD、TiKV、TiDB、TiFlash、TiCDC 进行垂直扩缩容。

- 如果要对 PD、TiKV、TiDB 进行垂直扩缩容,通过 kubectl 修改集群所对应的 `TidbCluster` 对象的 `spec.pd.resources``spec.tikv.resources``spec.tidb.resources` 至期望值。
- 如果要对 PD、TiKV、TiDB、TiProxy 进行垂直扩缩容,通过 kubectl 修改集群所对应的 `TidbCluster` 对象的 `spec.pd.resources``spec.tikv.resources``spec.tidb.resources` 至期望值。

- 如果要对 TiFlash 进行垂直扩缩容,修改 `spec.tiflash.resources` 至期望值。

Expand Down
1 change: 1 addition & 0 deletions zh/suspend-tidb-cluster.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,7 @@ summary: 了解如何通过配置挂起 Kubernetes 上的 TiDB 集群。
* TiCDC
* TiKV
* Pump
* TiProxy
* PD

## 恢复 TiDB 集群
Expand Down
2 changes: 1 addition & 1 deletion zh/upgrade-a-tidb-cluster.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ aliases: ['/docs-cn/tidb-in-kubernetes/dev/upgrade-a-tidb-cluster/']

Kubernetes 提供了[滚动更新功能](https://kubernetes.io/docs/tutorials/kubernetes-basics/update/update-intro/),在不影响应用可用性的前提下执行更新。

使用滚动更新时,TiDB Operator 会按 PD、TiFlash、TiKV、TiDB 的顺序,串行地删除旧版本的 Pod,并创建新版本的 Pod。当新版本的 Pod 正常运行后,再处理下一个 Pod。
使用滚动更新时,TiDB Operator 会按 PD、TiProxy、TiFlash、TiKV、TiDB 的顺序,串行地删除旧版本的 Pod,并创建新版本的 Pod。当新版本的 Pod 正常运行后,再处理下一个 Pod。

滚动更新中,TiDB Operator 会自动处理 PD 和 TiKV 的 Leader 迁移。因此,在多节点的部署拓扑下(最小环境:PD \* 3、TiKV \* 3、TiDB \* 2),滚动更新 TiKV、PD 不会影响业务正常运行。对于有连接重试功能的客户端,滚动更新 TiDB 同样不会影响业务。

Expand Down

0 comments on commit f4fdf83

Please sign in to comment.