Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

tiproxy: add basic document #2477

Merged
merged 15 commits into from
Jan 17, 2024
31 changes: 29 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` 为单个或多个组件开启。

hfxsd marked this conversation as resolved.
Show resolved Hide resolved
### 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,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"
```

xhebox marked this conversation as resolved.
Show resolved Hide resolved
获取所有可以配置的 TiProxy 配置参数,请参考 [TiProxy 配置文档](link)。
xhebox marked this conversation as resolved.
Show resolved Hide resolved

#### 配置 TiFlash 配置参数

你可以通过 TidbCluster CR 的 `spec.tiflash.config` 来配置 TiFlash 配置参数。
Expand Down Expand Up @@ -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 集群。
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 版本。
ran-huang marked this conversation as resolved.
Show resolved Hide resolved

## 退出和回收已加入的 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:
xhebox marked this conversation as resolved.
Show resolved Hide resolved

{{< 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)
45 changes: 44 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,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` 属性:
xhebox marked this conversation as resolved.
Show resolved Hide resolved

``` 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"
xhebox marked this conversation as resolved.
Show resolved Hide resolved
],
...
```

其中 `${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` 文件:
Expand Down Expand Up @@ -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" >}}
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,更改 Pod 镜像等配置,来手动触发重启。
xhebox marked this conversation as resolved.
Show resolved Hide resolved
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 进行垂直扩缩容。
xhebox marked this conversation as resolved.
Show resolved Hide resolved

- 如果要对 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
Loading