diff --git a/en/enable-tls-for-mysql-client.md b/en/enable-tls-for-mysql-client.md index 2e3c6616b..683165a98 100644 --- a/en/enable-tls-for-mysql-client.md +++ b/en/enable-tls-for-mysql-client.md @@ -9,7 +9,7 @@ This document describes how to enable TLS for MySQL client of the TiDB cluster o To enable TLS for the MySQL client, perform the following steps: -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. +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. > **Note:** > @@ -20,7 +20,9 @@ To enable TLS for the MySQL client, perform the following steps: - [Using the `cfssl` system](#using-cfssl) - [Using the `cert-manager` system](#using-cert-manager) -2. [Deploy the cluster](#deploy-the-tidb-cluster), and set `.spec.tidb.tlsClient.enabled` to `true`. + If you need to renew the existing TLS certificate, refer to [Renew and Replace the TLS Certificate](renew-tls-certificate.md). + +2. [Deploy the cluster](#step-2-deploy-the-tidb-cluster), and set `.spec.tidb.tlsClient.enabled` to `true`. * 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`. * 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). @@ -30,11 +32,9 @@ To enable TLS for the MySQL client, perform the following steps: > > For an existing cluster, if you change `.spec.tidb.tlsClient.enabled` from `false` to `true`, the TiDB Pods will be rolling restarted. -3. [Configure the MySQL client to use an encrypted connection](#configure-the-mysql-client-to-use-an-encrypted-connection). - -If you need to renew the existing TLS certificate, refer to [Renew and Replace the TLS Certificate](renew-tls-certificate.md). +3. [Configure the MySQL client to use an encrypted connection](#step-3-configure-the-mysql-client-to-use-a-tls-connection). -## Issue two sets of certificates for the TiDB cluster +## Step 1. Issue two sets of certificates for the TiDB cluster This section describes how to issue certificates for the TiDB cluster using two methods: `cfssl` and `cert-manager`. @@ -508,7 +508,7 @@ You can generate multiple sets of client-side certificates. At least one set of > > 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. -## Deploy the TiDB cluster +## Step 2. Deploy the TiDB cluster In this step, you create a TiDB cluster and perform the following operations: @@ -636,16 +636,16 @@ In this step, you create a TiDB cluster and perform the following operations: kubectl apply -f restore.yaml ``` -## Configure the MySQL client to use an encrypted connection +## Step 3. Configure the MySQL client to use a TLS connection 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). Execute the following command to acquire the client-side certificate and connect to the TiDB server: ``` 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 +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 ``` ``` shell @@ -654,6 +654,51 @@ mysql --comments -uroot -p -P 4000 -h ${tidb_host} --ssl-cert=client-tls.crt --s 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). +When not relying on client certificates the following is sufficient: + +``` shell +kubectl get secret -n ${namespace} ${cluster_name}-tidb-client-secret -ojsonpath='{.data.ca\.crt}' | base64 --decode > client-ca.crt +``` + +``` shell +mysql --comments -uroot -p -P 4000 -h ${tidb_host} --ssl-ca=client-ca.crt +``` + +## Troubleshooting + +The X.509 certificates are stored in Kubernetes secrets. To inspect them, use commands similar to `kubectl -n ${namespace} get secret`. + +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. + +To check these secret mounts from inside the container, run the following command: + +``` shell +kubectl exec -n ${cluster_name} --stdin=true --tty=true ${cluster_name}-tidb-0 -c tidb -- /bin/sh +``` + +The contents of the TLS directories is as follows: + +``` shell +sh-5.1# ls -l /var/lib/*tls +/var/lib/tidb-server-tls: +total 0 +lrwxrwxrwx. 1 root root 13 Sep 25 12:23 ca.crt -> ..data/ca.crt +lrwxrwxrwx. 1 root root 14 Sep 25 12:23 tls.crt -> ..data/tls.crt +lrwxrwxrwx. 1 root root 14 Sep 25 12:23 tls.key -> ..data/tls.key + +/var/lib/tidb-tls: +total 0 +lrwxrwxrwx. 1 root root 13 Sep 25 12:23 ca.crt -> ..data/ca.crt +lrwxrwxrwx. 1 root root 14 Sep 25 12:23 tls.crt -> ..data/tls.crt +lrwxrwxrwx. 1 root root 14 Sep 25 12:23 tls.key -> ..data/tls.key +``` + +The output of `kubectl -n ${cluster_name} logs ${cluster_name}-tidb-0 -c tidb` is as follows: + +``` +[2025/09/25 12:23:19.739 +00:00] [INFO] [server.go:291] ["mysql protocol server secure connection is enabled"] ["client verification enabled"=true] +``` + ## Reload certificates The certificate reload process depends on how you generate certificates: diff --git a/en/restore-data-using-tidb-lightning.md b/en/restore-data-using-tidb-lightning.md index c9ba1e2ee..a88879d4b 100644 --- a/en/restore-data-using-tidb-lightning.md +++ b/en/restore-data-using-tidb-lightning.md @@ -56,7 +56,7 @@ If TLS between components has been enabled on the target TiDB cluster (`spec.tls 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. -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`. +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`. > **Note:** > diff --git a/zh/enable-tls-for-mysql-client.md b/zh/enable-tls-for-mysql-client.md index 6ae850390..162397125 100644 --- a/zh/enable-tls-for-mysql-client.md +++ b/zh/enable-tls-for-mysql-client.md @@ -7,13 +7,20 @@ summary: 在 Kubernetes 上如何为 TiDB 集群的 MySQL 客户端开启 TLS。 本文主要描述了在 Kubernetes 上如何为 TiDB 集群的 MySQL 客户端开启 TLS。TiDB Operator 从 v1.1 开始已经支持为 Kubernetes 上 TiDB 集群开启 MySQL 客户端 TLS。开启步骤为: -1. 为 TiDB Server 颁发一套 Server 端证书,为 MySQL Client 颁发一套 Client 端证书。并创建两个 Secret 对象,Secret 名字分别为:`${cluster_name}-tidb-server-secret` 和 `${cluster_name}-tidb-client-secret`,分别包含前面创建的两套证书; +1. [为 TiDB Server 颁发一套 Server 端证书](#第一步为-tidb-集群颁发两套证书),为 MySQL Client 颁发一套 Client 端证书。并创建两个 Secret 对象,Secret 名字分别为:`${cluster_name}-tidb-server-secret` 和 `${cluster_name}-tidb-client-secret`,分别包含前面创建的两套证书; > **注意:** > > 创建的 Secret 对象必须符合上述命名规范,否则将导致 TiDB 集群部署失败。 -2. 部署集群,设置 `.spec.tidb.tlsClient.enabled` 属性为 `true`: + 其中,颁发证书的方式有多种,本文档提供两种方式,用户也可以根据需要为 TiDB 集群颁发证书,这两种方式分别为: + + - [使用 `cfssl` 系统颁发证书](#使用-cfssl-系统颁发证书) + - [使用 `cert-manager` 系统颁发证书](#使用-cert-manager-颁发证书) + + 当需要更新已有 TLS 证书时,可参考[更新和替换 TLS 证书](renew-tls-certificate.md)。 + +2. [部署集群](#第二步部署-tidb-集群),设置 `.spec.tidb.tlsClient.enabled` 属性为 `true`: * 如需跳过作为 MySQL 客户端的内部组件(如 TidbInitializer、Dashboard、Backup、Restore)的 TLS 认证,你可以给集群对应的 `TidbCluster` 加上 `tidb.tidb.pingcap.com/skip-tls-when-connect-tidb="true"` 的 annotation。 * 如需关闭 TiDB 服务端对客户端 CA 证书的认证,你可以设置 `.spec.tidb.tlsClient.disableClientAuthn` 属性为 `true`,即在[配置 TiDB 服务端启用安全连接](https://docs.pingcap.com/zh/tidb/stable/enable-tls-between-clients-and-servers#配置-tidb-服务端启用安全连接) 中不设置 ssl-ca 参数。 @@ -23,14 +30,7 @@ summary: 在 Kubernetes 上如何为 TiDB 集群的 MySQL 客户端开启 TLS。 > > 已部署的集群 `.spec.tidb.tlsClient.enabled` 属性从 `false` 改为 `true`,将导致 TiDB Pod 滚动重启。 -3. 配置 MySQL 客户端使用加密连接。 - -其中,颁发证书的方式有多种,本文档提供两种方式,用户也可以根据需要为 TiDB 集群颁发证书,这两种方式分别为: - -- 使用 `cfssl` 系统颁发证书; -- 使用 `cert-manager` 系统颁发证书; - -当需要更新已有 TLS 证书时,可参考[更新和替换 TLS 证书](renew-tls-certificate.md)。 +3. [配置 MySQL 客户端使用加密连接](#第三步配置-mysql-客户端使用-tls-连接)。 ## 第一步:为 TiDB 集群颁发两套证书 @@ -38,8 +38,6 @@ summary: 在 Kubernetes 上如何为 TiDB 集群的 MySQL 客户端开启 TLS。 1. 首先下载 `cfssl` 软件并初始化证书颁发机构: - {{< copyable "shell-regular" >}} - ``` shell mkdir -p ~/bin curl -s -L -o ~/bin/cfssl https://pkg.cfssl.org/R1.2/cfssl_linux-amd64 @@ -109,8 +107,6 @@ summary: 在 Kubernetes 上如何为 TiDB 集群的 MySQL 客户端开启 TLS。 4. 使用定义的选项生成 CA: - {{< copyable "shell-regular" >}} - ``` shell cfssl gencert -initca ca-csr.json | cfssljson -bare ca - ``` @@ -119,8 +115,6 @@ summary: 在 Kubernetes 上如何为 TiDB 集群的 MySQL 客户端开启 TLS。 首先生成默认的 `server.json` 文件: - {{< copyable "shell-regular" >}} - ``` shell cfssl print-defaults csr > server.json ``` @@ -150,8 +144,6 @@ summary: 在 Kubernetes 上如何为 TiDB 集群的 MySQL 客户端开启 TLS。 最后生成 Server 端证书: - {{< 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 ``` @@ -160,8 +152,6 @@ summary: 在 Kubernetes 上如何为 TiDB 集群的 MySQL 客户端开启 TLS。 首先生成默认的 `client.json` 文件: - {{< copyable "shell-regular" >}} - ``` shell cfssl print-defaults csr > client.json ``` @@ -177,8 +167,6 @@ summary: 在 Kubernetes 上如何为 TiDB 集群的 MySQL 客户端开启 TLS。 最后生成 Client 端证书: - {{< 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 ``` @@ -187,8 +175,6 @@ summary: 在 Kubernetes 上如何为 TiDB 集群的 MySQL 客户端开启 TLS。 到这里假设你已经按照上述文档把两套证书都创建好了。通过下面的命令为 TiDB 集群创建 Secret 对象: - {{< 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 @@ -213,8 +199,6 @@ summary: 在 Kubernetes 上如何为 TiDB 集群的 MySQL 客户端开启 TLS。 首先创建一个目录保存 `cert-manager` 创建证书所需文件: - {{< copyable "shell-regular" >}} - ``` shell mkdir -p cert-manager cd cert-manager @@ -264,8 +248,6 @@ summary: 在 Kubernetes 上如何为 TiDB 集群的 MySQL 客户端开启 TLS。 最后执行下面的命令进行创建: - {{< copyable "shell-regular" >}} - ``` shell kubectl apply -f tidb-server-issuer.yaml ``` @@ -333,8 +315,6 @@ summary: 在 Kubernetes 上如何为 TiDB 集群的 MySQL 客户端开启 TLS。 通过执行下面的命令来创建证书: - {{< copyable "shell-regular" >}} - ``` shell kubectl apply -f tidb-server-cert.yaml ``` @@ -377,8 +357,6 @@ summary: 在 Kubernetes 上如何为 TiDB 集群的 MySQL 客户端开启 TLS。 通过执行下面的命令来创建证书: - {{< copyable "shell-regular" >}} - ``` shell kubectl apply -f tidb-client-cert.yaml ``` @@ -516,8 +494,6 @@ summary: 在 Kubernetes 上如何为 TiDB 集群的 MySQL 客户端开启 TLS。 2. 通过执行下面的命令来创建证书: - {{< copyable "shell-regular" >}} - ``` shell kubectl apply -f tidb-components-client-cert.yaml ``` @@ -640,50 +616,97 @@ summary: 在 Kubernetes 上如何为 TiDB 集群的 MySQL 客户端开启 TLS。 2. 部署 TiDB 集群: - {{< copyable "shell-regular" >}} - ``` shell kubectl apply -f tidb-cluster.yaml ``` 3. 集群备份: - {{< copyable "shell-regular" >}} - ``` shell kubectl apply -f backup.yaml ``` 4. 集群恢复: - {{< copyable "shell-regular" >}} - ``` shell kubectl apply -f restore.yaml ``` -## 第三步:配置 MySQL 客户端使用加密连接 +## 第三步:配置 MySQL 客户端使用 TLS 连接 可以根据[官网文档](https://docs.pingcap.com/zh/tidb/stable/enable-tls-between-clients-and-servers#配置-mysql-client-使用安全连接)提示,使用上面创建的 Client 证书,通过下面的方法连接 TiDB 集群: 获取 Client 证书的方式并连接 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 +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 ``` 最后请参考[官网文档](https://docs.pingcap.com/zh/tidb/stable/enable-tls-between-clients-and-servers#检查当前连接是否是加密连接)来验证是否正确开启了 TLS。 +如果不使用 Client 证书,可以运行以下命令: + +``` shell +kubectl get secret -n ${namespace} ${cluster_name}-tidb-client-secret -ojsonpath='{.data.ca\.crt}' | base64 --decode > client-ca.crt +``` + +``` shell +mysql --comments -uroot -p -P 4000 -h ${tidb_host} --ssl-ca=client-ca.crt +``` + +## 故障排查 + +X.509 证书存储在 Kubernetes Secret 中。可以使用类似下面的命令查看这些 Secret: + +```shell +kubectl -n ${namespace} get secret +``` + +这些 Secret 会被挂载到容器内。可以通过查看 Pod 描述中的 **Volumes** 部分来确认挂载的卷信息: + +```shell +kubectl -n ${namespace} describe pod ${podname} +``` + +要在容器内部检查这些 Secret 挂载情况,可以运行以下命令: + +```shell +kubectl exec -n ${cluster_name} --stdin=true --tty=true ${cluster_name}-tidb-0 -c tidb -- /bin/sh +``` + +在容器内查看 TLS 目录的内容: + +```shell +sh-5.1# ls -l /var/lib/*tls +/var/lib/tidb-server-tls: +total 0 +lrwxrwxrwx. 1 root root 13 Sep 25 12:23 ca.crt -> ..data/ca.crt +lrwxrwxrwx. 1 root root 14 Sep 25 12:23 tls.crt -> ..data/tls.crt +lrwxrwxrwx. 1 root root 14 Sep 25 12:23 tls.key -> ..data/tls.key + +/var/lib/tidb-tls: +total 0 +lrwxrwxrwx. 1 root root 13 Sep 25 12:23 ca.crt -> ..data/ca.crt +lrwxrwxrwx. 1 root root 14 Sep 25 12:23 tls.crt -> ..data/tls.crt +lrwxrwxrwx. 1 root root 14 Sep 25 12:23 tls.key -> ..data/tls.key +``` + +检查 TiDB 容器日志以确认 TLS 已启用,示例命令及输出如下: + +```shell +kubectl -n ${cluster_name} logs ${cluster_name}-tidb-0 -c tidb +``` + +``` +[2025/09/25 12:23:19.739 +00:00] [INFO] [server.go:291] ["mysql protocol server secure connection is enabled"] ["client verification enabled"=true] +``` + ## 重新加载证书 重新加载证书的方式取决于证书的生成方式: @@ -707,4 +730,4 @@ SHOW GLOBAL STATUS LIKE 'Ssl\_server\_not\_%'; | Ssl_server_not_before | Jan 24 07:59:47 2025 UTC | +-----------------------+--------------------------+ 2 rows in set (0.011 sec) -``` +``` \ No newline at end of file