Skip to content

enable-tls-for-mysql-client: add info about rotation of X.509 TLS certs #2946

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.

Sign up for GitHub

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

Merged
merged 3 commits into from
Oct 21, 2025
+50 −34
Merged

enable-tls-for-mysql-client: add info about rotation of X.509 TLS certs #2946

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
39329a7
enable-tls-for-mysql-client: add info about rotation of X.509 certs f…
dveeden Oct 6, 2025
d17f787
Update TLS certificate reload instructions for TiDB
hfxsd Oct 20, 2025
93fda7c
Apply suggestions from code review
dveeden Oct 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 25 additions & 34 deletions en/enable-tls-for-mysql-client.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,8 +43,6 @@ This section describes how to issue certificates for the TiDB cluster using two

1. Download `cfssl` and initialize the certificate issuer:

{{< copyable "shell-regular" >}}

```shell
mkdir -p ~/bin
curl -s -L -o ~/bin/cfssl https://pkg.cfssl.org/R1.2/cfssl_linux-amd64
Expand Down Expand Up @@ -114,8 +112,6 @@ This section describes how to issue certificates for the TiDB cluster using two

4. Generate CA by the configured option:

{{< copyable "shell-regular" >}}

```shell
cfssl gencert -initca ca-csr.json | cfssljson -bare ca -
```
Expand All @@ -124,8 +120,6 @@ This section describes how to issue certificates for the TiDB cluster using two

First, create the default `server.json` file:

{{< copyable "shell-regular" >}}

``` shell
cfssl print-defaults csr > server.json
```
Expand Down Expand Up @@ -155,8 +149,6 @@ This section describes how to issue certificates for the TiDB cluster using two

Finally, generate the server-side certificate:

{{< copyable "shell-regular" >}}

``` shell
cfssl gencert -ca=ca.pem -ca-key=ca-key.pem -config=ca-config.json -profile=server server.json | cfssljson -bare server
```
Expand All @@ -165,8 +157,6 @@ This section describes how to issue certificates for the TiDB cluster using two

First, create the default `client.json` file:

{{< copyable "shell-regular" >}}

``` shell
cfssl print-defaults csr > client.json
```
Expand All @@ -182,8 +172,6 @@ This section describes how to issue certificates for the TiDB cluster using two

Finally, generate the client-side certificate:

{{< copyable "shell-regular" >}}

``` shell
cfssl gencert -ca=ca.pem -ca-key=ca-key.pem -config=ca-config.json -profile=client client.json | cfssljson -bare client
```
Expand All @@ -192,8 +180,6 @@ This section describes how to issue certificates for the TiDB cluster using two

If you have already generated two sets of certificates as described in the above steps, create the Secret object for the TiDB cluster by the following command:

{{< copyable "shell-regular" >}}

```shell
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
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
Expand All @@ -218,8 +204,6 @@ You can generate multiple sets of client-side certificates. At least one set of

First, create a directory which saves the files that `cert-manager` needs to create certificates:

{{< copyable "shell-regular" >}}

``` shell
mkdir -p cert-manager
cd cert-manager
Expand Down Expand Up @@ -269,8 +253,6 @@ You can generate multiple sets of client-side certificates. At least one set of

Finally, execute the following command to create an Issuer:

{{< copyable "shell-regular" >}}

``` shell
kubectl apply -f tidb-server-issuer.yaml
```
Expand Down Expand Up @@ -338,8 +320,6 @@ You can generate multiple sets of client-side certificates. At least one set of

Execute the following command to generate the certificate:

{{< copyable "shell-regular" >}}

``` shell
kubectl apply -f tidb-server-cert.yaml
```
Expand Down Expand Up @@ -382,8 +362,6 @@ You can generate multiple sets of client-side certificates. At least one set of

Execute the following command to generate the certificate:

{{< copyable "shell-regular" >}}

``` shell
kubectl apply -f tidb-client-cert.yaml
```
Expand Down Expand Up @@ -521,8 +499,6 @@ You can generate multiple sets of client-side certificates. At least one set of

2. Create the certificate by running the following command:

{{< copyable "shell-regular" >}}

``` shell
kubectl apply -f tidb-components-client-cert.yaml
```
Expand Down Expand Up @@ -645,24 +621,18 @@ In this step, you create a TiDB cluster and perform the following operations:

2. Deploy the TiDB cluster:

{{< copyable "shell-regular" >}}

``` shell
kubectl apply -f tidb-cluster.yaml
```

3. Back up the cluster:

{{< copyable "shell-regular" >}}

``` shell
kubectl apply -f backup.yaml
```

4. Restore the cluster:

{{< copyable "shell-regular" >}}

``` shell
kubectl apply -f restore.yaml
```
Expand All @@ -673,18 +643,39 @@ To connect the MySQL client with the TiDB cluster, use the client-side certifica

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

{{< copyable "shell-regular" >}}

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

{{< copyable "shell-regular" >}}

``` shell
mysql --comments -uroot -p -P 4000 -h ${tidb_host} --ssl-cert=client-tls.crt --ssl-key=client-tls.key --ssl-ca=client-ca.crt
```

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).

## Reload certificates

The certificate reload process depends on how you generate certificates:

- If you generate the certificate and key files manually using `cfssl`, you must update the corresponding Secret manually.
- If you generate the certificate and key files using `cert-manager`, the Secret is updated automatically whenever a new certificate is issued.

To let TiDB use the new certificate, run [`ALTER INSTANCE RELOAD TLS`](https://docs.pingcap.com/tidb/stable/sql-statement-alter-instance/#reload-tls).

To verify the certificate validity period, run the following SQL statement to check the `Ssl_server_not_before` and `Ssl_server_not_after` status variables:

```sql
SHOW GLOBAL STATUS LIKE 'Ssl\_server\_not\_%';
```

```
+-----------------------+--------------------------+
| Variable_name | Value |
+-----------------------+--------------------------+
| Ssl_server_not_after | Apr 23 07:59:47 2026 UTC |
| Ssl_server_not_before | Jan 24 07:59:47 2025 UTC |
+-----------------------+--------------------------+
2 rows in set (0.011 sec)
```
25 changes: 25 additions & 0 deletions zh/enable-tls-for-mysql-client.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -684,3 +684,28 @@ mysql --comments -uroot -p -P 4000 -h ${tidb_host} --ssl-cert=client-tls.crt --s
```

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

## 重新加载证书

重新加载证书的方式取决于证书的生成方式：

- 如果使用 `cfssl` 手动生成证书和密钥文件，必须手动更新对应的 Secret。
- 如果使用 `cert-manager` 生成证书和密钥文件，Secret 在颁发新证书时会自动更新。

要让 TiDB 使用新的证书，需要运行 [`ALTER INSTANCE RELOAD TLS`](https://docs.pingcap.com/zh/tidb/stable/sql-statement-alter-instance#reload-tls)。

可以执行下面语句查看状态变量 `Ssl_server_not_before` 和 `Ssl_server_not_after` 来检查证书的有效期。

```sql
SHOW GLOBAL STATUS LIKE 'Ssl\_server\_not\_%';
```

```
+-----------------------+--------------------------+
| Variable_name | Value |
+-----------------------+--------------------------+
| Ssl_server_not_after | Apr 23 07:59:47 2026 UTC |
| Ssl_server_not_before | Jan 24 07:59:47 2025 UTC |
+-----------------------+--------------------------+
2 rows in set (0.011 sec)
```