Skip to content

Commit 86f89db

Browse files
dveedendveeden
authored
enable-tls-for-mysql-client: Add info about TLS without client certs (#2942)
1 parent 2578d40 commit 86f89db

File tree

3 files changed

+129
-61
lines changed

3 files changed

+129
-61
lines changed

‎en/enable-tls-for-mysql-client.md‎

Lines changed: 56 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ This document describes how to enable TLS for MySQL client of the TiDB cluster o
1010

1111
To enable TLS for the MySQL client, perform the following steps:
1212

13-
1. [Issue two sets of certificates](#issue-two-sets-of-certificates-for-the-tidb-cluster): a set of server-side certificates for TiDB server, and a set of client-side certificates for MySQL client. Create two Secret objects, `${cluster_name}-tidb-server-secret` and `${cluster_name}-tidb-client-secret`, respectively including these two sets of certificates.
13+
1. [Issue two sets of certificates](#step-1-issue-two-sets-of-certificates-for-the-tidb-cluster): a set of server-side certificates for TiDB server, and a set of client-side certificates for MySQL client. Create two Secret objects, `${cluster_name}-tidb-server-secret` and `${cluster_name}-tidb-client-secret`, respectively including these two sets of certificates.
1414

1515
> **Note:**
1616
>
@@ -21,7 +21,9 @@ To enable TLS for the MySQL client, perform the following steps:
2121
- [Using the `cfssl` system](#using-cfssl)
2222
- [Using the `cert-manager` system](#using-cert-manager)
2323

24-
2. [Deploy the cluster](#deploy-the-tidb-cluster), and set `.spec.tidb.tlsClient.enabled` to `true`.
24+
If you need to renew the existing TLS certificate, refer to [Renew and Replace the TLS Certificate](renew-tls-certificate.md).
25+
26+
2. [Deploy the cluster](#step-2-deploy-the-tidb-cluster), and set `.spec.tidb.tlsClient.enabled` to `true`.
2527

2628
* To skip TLS authentication for internal components that serve as the MySQL client (such as TidbInitializer, Dashboard, Backup, and Restore), you can add the `tidb.tidb.pingcap.com/skip-tls-when-connect-tidb="true"` annotation to the cluster's corresponding `TidbCluster`.
2729
* To disable the client CA certificate authentication on the TiDB server, you can set `.spec.tidb.tlsClient.disableClientAuthn` to `true`. This means skipping setting the `ssl-ca` parameter when you [configure TiDB server to enable secure connections](https://docs.pingcap.com/tidb/stable/enable-tls-between-clients-and-servers#configure-tidb-server-to-use-secure-connections).
@@ -31,11 +33,9 @@ To enable TLS for the MySQL client, perform the following steps:
3133
>
3234
> For an existing cluster, if you change `.spec.tidb.tlsClient.enabled` from `false` to `true`, the TiDB Pods will be rolling restarted.
3335
34-
3. [Configure the MySQL client to use an encrypted connection](#configure-the-mysql-client-to-use-an-encrypted-connection).
35-
36-
If you need to renew the existing TLS certificate, refer to [Renew and Replace the TLS Certificate](renew-tls-certificate.md).
36+
3. [Configure the MySQL client to use an encrypted connection](#step-3-configure-the-mysql-client-to-use-a-tls-connection).
3737

38-
## Issue two sets of certificates for the TiDB cluster
38+
## Step 1. Issue two sets of certificates for the TiDB cluster
3939

4040
This section describes how to issue certificates for the TiDB cluster using two methods: `cfssl` and `cert-manager`.
4141

@@ -509,7 +509,7 @@ You can generate multiple sets of client-side certificates. At least one set of
509509
>
510510
> TiDB server's TLS is compatible with the MySQL protocol. When the certificate content is changed, the administrator needs to manually execute the SQL statement `alter instance reload tls` to refresh the content.
511511

512-
## Deploy the TiDB cluster
512+
## Step 2. Deploy the TiDB cluster
513513

514514
In this step, you create a TiDB cluster and perform the following operations:
515515

@@ -637,16 +637,16 @@ In this step, you create a TiDB cluster and perform the following operations:
637637
kubectl apply -f restore.yaml
638638
```
639639

640-
## Configure the MySQL client to use an encrypted connection
640+
## Step 3. Configure the MySQL client to use a TLS connection
641641

642642
To connect the MySQL client with the TiDB cluster, use the client-side certificate created above and take the following methods. For details, refer to [Configure the MySQL client to use encrypted connections](https://docs.pingcap.com/tidb/stable/enable-tls-between-clients-and-servers#configure-the-mysql-client-to-use-encrypted-connections).
643643

644644
Execute the following command to acquire the client-side certificate and connect to the TiDB server:
645645

646646
``` shell
647-
kubectl get secret -n ${namespace} ${cluster_name}-tidb-client-secret -ojsonpath='{.data.tls\.crt}' | base64 --decode > client-tls.crt
648-
kubectl get secret -n ${namespace} ${cluster_name}-tidb-client-secret -ojsonpath='{.data.tls\.key}' | base64 --decode > client-tls.key
649-
kubectl get secret -n ${namespace} ${cluster_name}-tidb-client-secret -ojsonpath='{.data.ca\.crt}' | base64 --decode > client-ca.crt
647+
kubectl get secret -n ${namespace} ${cluster_name}-tidb-client-secret -ojsonpath='{.data.tls\.crt}' | base64 --decode > client-tls.crt
648+
kubectl get secret -n ${namespace} ${cluster_name}-tidb-client-secret -ojsonpath='{.data.tls\.key}' | base64 --decode > client-tls.key
649+
kubectl get secret -n ${namespace} ${cluster_name}-tidb-client-secret -ojsonpath='{.data.ca\.crt}' | base64 --decode > client-ca.crt
650650
```
651651

652652
``` shell
@@ -655,6 +655,51 @@ mysql --comments -uroot -p -P 4000 -h ${tidb_host} --ssl-cert=client-tls.crt --s
655655

656656
Finally, to verify whether TLS is successfully enabled, refer to [checking the current connection](https://docs.pingcap.com/tidb/stable/enable-tls-between-clients-and-servers#check-whether-the-current-connection-uses-encryption).
657657

658+
When not relying on client certificates the following is sufficient:
659+
660+
``` shell
661+
kubectl get secret -n ${namespace} ${cluster_name}-tidb-client-secret -ojsonpath='{.data.ca\.crt}' | base64 --decode > client-ca.crt
662+
```
663+
664+
``` shell
665+
mysql --comments -uroot -p -P 4000 -h ${tidb_host} --ssl-ca=client-ca.crt
666+
```
667+
668+
## Troubleshooting
669+
670+
The X.509 certificates are stored in Kubernetes secrets. To inspect them, use commands similar to `kubectl -n ${namespace} get secret`.
671+
672+
These secrets are mounted into the containers. To view the volume mounts, check the **Volumes** section in the output of the `kubectl -n ${namespace} describe pod ${podname}` command.
673+
674+
To check these secret mounts from inside the container, run the following command:
675+
676+
``` shell
677+
kubectl exec -n ${cluster_name} --stdin=true --tty=true ${cluster_name}-tidb-0 -c tidb -- /bin/sh
678+
```
679+
680+
The contents of the TLS directories is as follows:
681+
682+
``` shell
683+
sh-5.1# ls -l /var/lib/*tls
684+
/var/lib/tidb-server-tls:
685+
total 0
686+
lrwxrwxrwx. 1 root root 13 Sep 25 12:23 ca.crt -> ..data/ca.crt
687+
lrwxrwxrwx. 1 root root 14 Sep 25 12:23 tls.crt -> ..data/tls.crt
688+
lrwxrwxrwx. 1 root root 14 Sep 25 12:23 tls.key -> ..data/tls.key
689+
690+
/var/lib/tidb-tls:
691+
total 0
692+
lrwxrwxrwx. 1 root root 13 Sep 25 12:23 ca.crt -> ..data/ca.crt
693+
lrwxrwxrwx. 1 root root 14 Sep 25 12:23 tls.crt -> ..data/tls.crt
694+
lrwxrwxrwx. 1 root root 14 Sep 25 12:23 tls.key -> ..data/tls.key
695+
```
696+
697+
The output of `kubectl -n ${cluster_name} logs ${cluster_name}-tidb-0 -c tidb` is as follows:
698+
699+
```
700+
[2025/09/25 12:23:19.739 +00:00] [INFO] [server.go:291] ["mysql protocol server secure connection is enabled"] ["client verification enabled"=true]
701+
```
702+
658703
## Reload certificates
659704

660705
The certificate reload process depends on how you generate certificates:

‎en/restore-data-using-tidb-lightning.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@ If TLS between components has been enabled on the target TiDB cluster (`spec.tls
5757

5858
If the target TiDB cluster has enabled TLS for the MySQL client (`spec.tidb.tlsClient.enabled: true`), and the corresponding client-side certificate is configured (the Kubernetes Secret object is `${cluster_name}-tidb-client-secret`), you can configure `tlsClient.enabled: true` in `values.yaml` to enable TiDB Lightning to connect to the TiDB server using TLS.
5959

60-
To use different client certificates to connect to the TiDB server, refer to [Issue two sets of certificates for the TiDB cluster](enable-tls-for-mysql-client.md#issue-two-sets-of-certificates-for-the-tidb-cluster) to generate the client-side certificate for TiDB Lightning, and configure the corresponding Kubernetes secret object in `tlsCluster.tlsClientSecretName` in `values.yaml`.
60+
To use different client certificates to connect to the TiDB server, refer to [Issue two sets of certificates for the TiDB cluster](enable-tls-for-mysql-client.md#step-1-issue-two-sets-of-certificates-for-the-tidb-cluster) to generate the client-side certificate for TiDB Lightning, and configure the corresponding Kubernetes secret object in `tlsCluster.tlsClientSecretName` in `values.yaml`.
6161

6262
> **Note:**
6363
>

‎zh/enable-tls-for-mysql-client.md‎

Lines changed: 72 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -8,13 +8,20 @@ aliases: ['/docs-cn/tidb-in-kubernetes/dev/enable-tls-for-mysql-client/']
88

99
本文主要描述了在 Kubernetes 上如何为 TiDB 集群的 MySQL 客户端开启 TLS。TiDB Operator 从 v1.1 开始已经支持为 Kubernetes 上 TiDB 集群开启 MySQL 客户端 TLS。开启步骤为：
1010

11-
1. 为 TiDB Server 颁发一套 Server 端证书，为 MySQL Client 颁发一套 Client 端证书。并创建两个 Secret 对象，Secret 名字分别为：`${cluster_name}-tidb-server-secret` 和 `${cluster_name}-tidb-client-secret`，分别包含前面创建的两套证书；
11+
1. [为 TiDB Server 颁发一套 Server 端证书](#第一步为-tidb-集群颁发两套证书)，为 MySQL Client 颁发一套 Client 端证书。并创建两个 Secret 对象，Secret 名字分别为：`${cluster_name}-tidb-server-secret` 和 `${cluster_name}-tidb-client-secret`，分别包含前面创建的两套证书；
1212

1313
> **注意：**
1414
>
1515
> 创建的 Secret 对象必须符合上述命名规范，否则将导致 TiDB 集群部署失败。
1616
17-
2. 部署集群，设置 `.spec.tidb.tlsClient.enabled` 属性为 `true`：
17+
其中，颁发证书的方式有多种，本文档提供两种方式，用户也可以根据需要为 TiDB 集群颁发证书，这两种方式分别为：
18+
19+
- [使用 `cfssl` 系统颁发证书](#使用-cfssl-系统颁发证书)
20+
- [使用 `cert-manager` 系统颁发证书](#使用-cert-manager-颁发证书)
21+
22+
当需要更新已有 TLS 证书时，可参考[更新和替换 TLS 证书](renew-tls-certificate.md)。
23+
24+
2. [部署集群](#第二步部署-tidb-集群)，设置 `.spec.tidb.tlsClient.enabled` 属性为 `true`：
1825

1926
* 如需跳过作为 MySQL 客户端的内部组件（如 TidbInitializer、Dashboard、Backup、Restore）的 TLS 认证，你可以给集群对应的 `TidbCluster` 加上 `tidb.tidb.pingcap.com/skip-tls-when-connect-tidb="true"` 的 annotation。
2027
* 如需关闭 TiDB 服务端对客户端 CA 证书的认证，你可以设置 `.spec.tidb.tlsClient.disableClientAuthn` 属性为 `true`，即在[配置 TiDB 服务端启用安全连接](https://docs.pingcap.com/zh/tidb/stable/enable-tls-between-clients-and-servers#配置-tidb-服务端启用安全连接) 中不设置 ssl-ca 参数。
@@ -24,23 +31,14 @@ aliases: ['/docs-cn/tidb-in-kubernetes/dev/enable-tls-for-mysql-client/']
2431
>
2532
> 已部署的集群 `.spec.tidb.tlsClient.enabled` 属性从 `false` 改为 `true`，将导致 TiDB Pod 滚动重启。
2633
27-
3. 配置 MySQL 客户端使用加密连接。
28-
29-
其中，颁发证书的方式有多种，本文档提供两种方式，用户也可以根据需要为 TiDB 集群颁发证书，这两种方式分别为：
30-
31-
- 使用 `cfssl` 系统颁发证书；
32-
- 使用 `cert-manager` 系统颁发证书；
33-
34-
当需要更新已有 TLS 证书时，可参考[更新和替换 TLS 证书](renew-tls-certificate.md)。
34+
3. [配置 MySQL 客户端使用加密连接](#第三步配置-mysql-客户端使用-tls-连接)。
3535

3636
## 第一步：为 TiDB 集群颁发两套证书
3737

3838
### 使用 `cfssl` 系统颁发证书
3939

4040
1. 首先下载 `cfssl` 软件并初始化证书颁发机构：
4141

42-
{{< copyable "shell-regular" >}}
43-
4442
``` shell
4543
mkdir -p ~/bin
4644
curl -s -L -o ~/bin/cfssl https://pkg.cfssl.org/R1.2/cfssl_linux-amd64
@@ -110,8 +108,6 @@ aliases: ['/docs-cn/tidb-in-kubernetes/dev/enable-tls-for-mysql-client/']
110108

111109
4. 使用定义的选项生成 CA：
112110

113-
{{< copyable "shell-regular" >}}
114-
115111
``` shell
116112
cfssl gencert -initca ca-csr.json | cfssljson -bare ca -
117113
```
@@ -120,8 +116,6 @@ aliases: ['/docs-cn/tidb-in-kubernetes/dev/enable-tls-for-mysql-client/']
120116

121117
首先生成默认的 `server.json` 文件：
122118

123-
{{< copyable "shell-regular" >}}
124-
125119
``` shell
126120
cfssl print-defaults csr > server.json
127121
```
@@ -151,8 +145,6 @@ aliases: ['/docs-cn/tidb-in-kubernetes/dev/enable-tls-for-mysql-client/']
151145

152146
最后生成 Server 端证书：
153147

154-
{{< copyable "shell-regular" >}}
155-
156148
``` shell
157149
cfssl gencert -ca=ca.pem -ca-key=ca-key.pem -config=ca-config.json -profile=server server.json | cfssljson -bare server
158150
```
@@ -161,8 +153,6 @@ aliases: ['/docs-cn/tidb-in-kubernetes/dev/enable-tls-for-mysql-client/']
161153

162154
首先生成默认的 `client.json` 文件：
163155

164-
{{< copyable "shell-regular" >}}
165-
166156
``` shell
167157
cfssl print-defaults csr > client.json
168158
```
@@ -178,8 +168,6 @@ aliases: ['/docs-cn/tidb-in-kubernetes/dev/enable-tls-for-mysql-client/']
178168

179169
最后生成 Client 端证书：
180170

181-
{{< copyable "shell-regular" >}}
182-
183171
``` shell
184172
cfssl gencert -ca=ca.pem -ca-key=ca-key.pem -config=ca-config.json -profile=client client.json | cfssljson -bare client
185173
```
@@ -188,8 +176,6 @@ aliases: ['/docs-cn/tidb-in-kubernetes/dev/enable-tls-for-mysql-client/']
188176

189177
到这里假设你已经按照上述文档把两套证书都创建好了。通过下面的命令为 TiDB 集群创建 Secret 对象：
190178

191-
{{< copyable "shell-regular" >}}
192-
193179
``` shell
194180
kubectl create secret generic ${cluster_name}-tidb-server-secret --namespace=${namespace} --from-file=tls.crt=server.pem --from-file=tls.key=server-key.pem --from-file=ca.crt=ca.pem
195181
kubectl create secret generic ${cluster_name}-tidb-client-secret --namespace=${namespace} --from-file=tls.crt=client.pem --from-file=tls.key=client-key.pem --from-file=ca.crt=ca.pem
@@ -214,8 +200,6 @@ aliases: ['/docs-cn/tidb-in-kubernetes/dev/enable-tls-for-mysql-client/']
214200

215201
首先创建一个目录保存 `cert-manager` 创建证书所需文件：
216202

217-
{{< copyable "shell-regular" >}}
218-
219203
``` shell
220204
mkdir -p cert-manager
221205
cd cert-manager
@@ -265,8 +249,6 @@ aliases: ['/docs-cn/tidb-in-kubernetes/dev/enable-tls-for-mysql-client/']
265249

266250
最后执行下面的命令进行创建：
267251

268-
{{< copyable "shell-regular" >}}
269-
270252
``` shell
271253
kubectl apply -f tidb-server-issuer.yaml
272254
```
@@ -334,8 +316,6 @@ aliases: ['/docs-cn/tidb-in-kubernetes/dev/enable-tls-for-mysql-client/']
334316

335317
通过执行下面的命令来创建证书：
336318

337-
{{< copyable "shell-regular" >}}
338-
339319
``` shell
340320
kubectl apply -f tidb-server-cert.yaml
341321
```
@@ -378,8 +358,6 @@ aliases: ['/docs-cn/tidb-in-kubernetes/dev/enable-tls-for-mysql-client/']
378358

379359
通过执行下面的命令来创建证书：
380360

381-
{{< copyable "shell-regular" >}}
382-
383361
``` shell
384362
kubectl apply -f tidb-client-cert.yaml
385363
```
@@ -517,8 +495,6 @@ aliases: ['/docs-cn/tidb-in-kubernetes/dev/enable-tls-for-mysql-client/']
517495

518496
2. 通过执行下面的命令来创建证书：
519497

520-
{{< copyable "shell-regular" >}}
521-
522498
``` shell
523499
kubectl apply -f tidb-components-client-cert.yaml
524500
```
@@ -641,50 +617,97 @@ aliases: ['/docs-cn/tidb-in-kubernetes/dev/enable-tls-for-mysql-client/']
641617

642618
2. 部署 TiDB 集群：
643619

644-
{{< copyable "shell-regular" >}}
645-
646620
``` shell
647621
kubectl apply -f tidb-cluster.yaml
648622
```
649623

650624
3. 集群备份：
651625

652-
{{< copyable "shell-regular" >}}
653-
654626
``` shell
655627
kubectl apply -f backup.yaml
656628
```
657629

658630
4. 集群恢复：
659631

660-
{{< copyable "shell-regular" >}}
661-
662632
``` shell
663633
kubectl apply -f restore.yaml
664634
```
665635

666-
## 第三步：配置 MySQL 客户端使用加密连接
636+
## 第三步：配置 MySQL 客户端使用 TLS 连接
667637

668638
可以根据[官网文档](https://docs.pingcap.com/zh/tidb/stable/enable-tls-between-clients-and-servers#配置-mysql-client-使用安全连接)提示，使用上面创建的 Client 证书，通过下面的方法连接 TiDB 集群：
669639

670640
获取 Client 证书的方式并连接 TiDB Server 的方法是：
671641

672-
{{< copyable "shell-regular" >}}
673-
674642
``` shell
675-
kubectl get secret -n ${namespace} ${cluster_name}-tidb-client-secret -ojsonpath='{.data.tls\.crt}' | base64 --decode > client-tls.crt
676-
kubectl get secret -n ${namespace} ${cluster_name}-tidb-client-secret -ojsonpath='{.data.tls\.key}' | base64 --decode > client-tls.key
677-
kubectl get secret -n ${namespace} ${cluster_name}-tidb-client-secret -ojsonpath='{.data.ca\.crt}' | base64 --decode > client-ca.crt
643+
kubectl get secret -n ${namespace} ${cluster_name}-tidb-client-secret -ojsonpath='{.data.tls\.crt}' | base64 --decode > client-tls.crt
644+
kubectl get secret -n ${namespace} ${cluster_name}-tidb-client-secret -ojsonpath='{.data.tls\.key}' | base64 --decode > client-tls.key
645+
kubectl get secret -n ${namespace} ${cluster_name}-tidb-client-secret -ojsonpath='{.data.ca\.crt}' | base64 --decode > client-ca.crt
678646
```
679647

680-
{{< copyable "shell-regular" >}}
681-
682648
``` shell
683649
mysql --comments -uroot -p -P 4000 -h ${tidb_host} --ssl-cert=client-tls.crt --ssl-key=client-tls.key --ssl-ca=client-ca.crt
684650
```
685651

686652
最后请参考[官网文档](https://docs.pingcap.com/zh/tidb/stable/enable-tls-between-clients-and-servers#检查当前连接是否是加密连接)来验证是否正确开启了 TLS。
687653

654+
如果不使用 Client 证书，可以运行以下命令：
655+
656+
``` shell
657+
kubectl get secret -n ${namespace} ${cluster_name}-tidb-client-secret -ojsonpath='{.data.ca\.crt}' | base64 --decode > client-ca.crt
658+
```
659+
660+
``` shell
661+
mysql --comments -uroot -p -P 4000 -h ${tidb_host} --ssl-ca=client-ca.crt
662+
```
663+
664+
## 故障排查
665+
666+
X.509 证书存储在 Kubernetes Secret 中。可以使用类似下面的命令查看这些 Secret：
667+
668+
```shell
669+
kubectl -n ${namespace} get secret
670+
```
671+
672+
这些 Secret 会被挂载到容器内。可以通过查看 Pod 描述中的 **Volumes** 部分来确认挂载的卷信息：
673+
674+
```shell
675+
kubectl -n ${namespace} describe pod ${podname}
676+
```
677+
678+
要在容器内部检查这些 Secret 挂载情况，可以运行以下命令：
679+
680+
```shell
681+
kubectl exec -n ${cluster_name} --stdin=true --tty=true ${cluster_name}-tidb-0 -c tidb -- /bin/sh
682+
```
683+
684+
在容器内查看 TLS 目录的内容：
685+
686+
```shell
687+
sh-5.1# ls -l /var/lib/*tls
688+
/var/lib/tidb-server-tls:
689+
total 0
690+
lrwxrwxrwx. 1 root root 13 Sep 25 12:23 ca.crt -> ..data/ca.crt
691+
lrwxrwxrwx. 1 root root 14 Sep 25 12:23 tls.crt -> ..data/tls.crt
692+
lrwxrwxrwx. 1 root root 14 Sep 25 12:23 tls.key -> ..data/tls.key
693+
694+
/var/lib/tidb-tls:
695+
total 0
696+
lrwxrwxrwx. 1 root root 13 Sep 25 12:23 ca.crt -> ..data/ca.crt
697+
lrwxrwxrwx. 1 root root 14 Sep 25 12:23 tls.crt -> ..data/tls.crt
698+
lrwxrwxrwx. 1 root root 14 Sep 25 12:23 tls.key -> ..data/tls.key
699+
```
700+
701+
检查 TiDB 容器日志以确认 TLS 已启用，示例命令及输出如下：
702+
703+
```shell
704+
kubectl -n ${cluster_name} logs ${cluster_name}-tidb-0 -c tidb
705+
```
706+
707+
```
708+
[2025/09/25 12:23:19.739 +00:00] [INFO] [server.go:291] ["mysql protocol server secure connection is enabled"] ["client verification enabled"=true]
709+
```
710+
688711
## 重新加载证书
689712

690713
重新加载证书的方式取决于证书的生成方式：
@@ -708,4 +731,4 @@ SHOW GLOBAL STATUS LIKE 'Ssl\_server\_not\_%';
708731
| Ssl_server_not_before | Jan 24 07:59:47 2025 UTC |
709732
+-----------------------+--------------------------+
710733
2 rows in set (0.011 sec)
711-
```
734+
```

0 commit comments

Comments
 (0)