pd/tls: add upgrade tls description (#2710) (#2711)

pingcap · Feb 18, 2025 · 4a88e2c · 4a88e2c
1 parent 83eebb4
commit 4a88e2c
Show file tree

Hide file tree

Showing 4 changed files with 94 additions and 6 deletions.
diff --git a/en/configure-a-tidb-cluster.md b/en/configure-a-tidb-cluster.md
@@ -68,7 +68,7 @@ It is recommended that you configure `spec.pvReclaimPolicy: Retain` to ensure th
 
 #### mountClusterClientSecret
 
-PD and TiKV supports configuring `mountClusterClientSecret`. If [TLS is enabled between cluster components](enable-tls-between-components.md), it is recommended to configure `spec.pd.mountClusterClientSecret: true` and `spec.tikv.mountClusterClientSecret: true`. Under such configuration, TiDB Operator automatically mounts the `${cluster_name}-cluster-client-secret` certificate to the PD and TiKV container, so you can conveniently [use `pd-ctl` and `tikv-ctl`](enable-tls-between-components.md#configure-pd-ctl-tikv-ctl-and-connect-to-the-cluster).
+PD and TiKV supports configuring `mountClusterClientSecret`. If [TLS is enabled between cluster components](enable-tls-between-components.md), it is recommended to configure `spec.pd.mountClusterClientSecret: true` and `spec.tikv.mountClusterClientSecret: true`. Under such configuration, TiDB Operator automatically mounts the `${cluster_name}-cluster-client-secret` certificate to the PD and TiKV container, so you can conveniently [use `pd-ctl` and `tikv-ctl`](enable-tls-between-components.md#step-3-configure-pd-ctl-tikv-ctl-and-connect-to-the-cluster).
 
 #### startScriptVersion
 

diff --git a/en/enable-tls-between-components.md b/en/enable-tls-between-components.md
@@ -22,7 +22,8 @@ To enable TLS between TiDB components, perform the following steps:
 
     > **Note:**
     >
-    > After the cluster is created, do not modify this field; otherwise, the cluster will fail to upgrade. If you need to modify this field, delete the cluster and create a new one.
+    > - After the cluster is created, do not modify this field; otherwise, the cluster will fail to upgrade. If you need to modify this field, delete the cluster and create a new one.
+    > - If you cannot rebuild the cluster but need to enable TLS, see [Upgrade a non-TLS cluster to a TLS cluster](#upgrade-a-non-tls-cluster-to-a-tls-cluster).
 
 3. Configure `pd-ctl` and `tikv-ctl` to connect to the cluster.
 
@@ -38,7 +39,7 @@ Certificates can be issued in multiple methods. This document describes two meth
 
 If you need to renew the existing TLS certificate, refer to [Renew and Replace the TLS Certificate](renew-tls-certificate.md).
 
-## Generate certificates for components of the TiDB cluster
+## Step 1. Generate certificates for components of the TiDB cluster
 
 This section describes how to issue certificates using two methods: `cfssl` and `cert-manager`.
 
@@ -1306,7 +1307,7 @@ This section describes how to issue certificates using two methods: `cfssl` and
 
     After the object is created, `cert-manager` generates a `${cluster_name}-cluster-client-secret` Secret object to be used by the clients of the TiDB components.
 
-## Deploy the TiDB cluster
+## Step 2. Deploy the TiDB cluster
 
 When you deploy a TiDB cluster, you can enable TLS between TiDB components, and set the `cert-allowed-cn` configuration item (for TiDB, the configuration item is `cluster-verify-cn`) to verify the CN (Common Name) of each component's certificate.
 
@@ -1516,7 +1517,7 @@ In this step, you need to perform the following operations:
         kubectl apply -f restore.yaml
         ```
 
-## Configure `pd-ctl`, `tikv-ctl` and connect to the cluster
+## Step 3. Configure `pd-ctl`, `tikv-ctl` and connect to the cluster
 
 1. Mount the certificates.
 
@@ -1570,3 +1571,89 @@ In this step, you need to perform the following operations:
     cd /var/lib/cluster-client-tls
     /tikv-ctl --ca-path=ca.crt --cert-path=tls.crt --key-path=tls.key --host 127.0.0.1:20160 cluster
     ```
+
+## Upgrade a non-TLS cluster to a TLS cluster
+
+This section describes how to enable TLS encrypted communication for an existing non-TLS TiDB cluster.
+
+> **Note:**
+>
+> This operation is only applicable to existing clusters that cannot be rebuilt. Before starting, make sure that you fully understand each step and its potential risks.
+
+1. If the cluster contains multiple PD nodes, first reduce the number of PD nodes to 1.
+
+2. Refer to [Step 1. Generate certificates for components of the TiDB Cluster](#step-1-generate-certificates-for-components-of-the-tidb-cluster) to generate TLS certificates and create Kubernetes Secret objects.
+
+3. Enable TLS:
+
+    You can choose one of the following methods to enable TLS:
+
+    - Method 1: Execute the following command to update the TiDB cluster configuration. Wait for the PD Pod to restart before proceeding to the next step.
+
+        ```shell
+        kubectl patch tc ${cluster_name} -n ${namespace} --type merge -p '{
+          "spec": {
+            "tlsCluster": {
+              "enabled": true
+            }
+          }
+        }'
+        ```
+
+        Example output:
+
+        ```shell
+        tidbcluster.pingcap.com/basic patched
+        ```
+
+    - Method 2: Refer to [Step 2. Deploy the TiDB cluster](#step-2-deploy-the-tidb-cluster) to enable TLS and set the `cert-allowed-cn` configuration item (for TiDB, the configuration item is `cluster-verify-cn`) to verify the CN (Common Name) of each component's certificate.
+
+4. Configure PD nodes:
+
+    1. Use `kubectl exec` to enter the PD Pod and install `etcdctl`. For detailed installation steps, see the [etcdctl installation guide](https://etcd.io/docs/v3.4/install/). After installation, `etcdctl` is located in the extracted folder directory.
+
+    2. View the etcd member information. At this point, `peerURLs` use the HTTP protocol:
+
+        ```shell
+        ./etcdctl --endpoints https://127.0.0.1:2379 --cert /var/lib/pd-tls/tls.crt --key /var/lib/pd-tls/tls.key --cacert /var/lib/pd-tls/ca.crt member list
+        ```
+
+        Example output:
+
+        ```shell
+        # memberID        status   name        peerURLs                                          clientURL                                          isLearner
+        e94cfb12fa384e23, started, basic-pd-0, http://basic-pd-0.basic-pd-peer.pingcap.svc:2380, https://basic-pd-0.basic-pd-peer.pingcap.svc:2379, false
+        ```
+
+        Record the following information for the next step:
+    
+        - `memberID`: In the example, it is `e94cfb12fa384e23`.
+        - `peerURLs`: In the example, it is `http://basic-pd-0.basic-pd-peer.pingcap.svc:2380`.
+
+    3. Update the etcd member's `peerURLs` from HTTP to the HTTPS protocol:
+
+        ```shell
+        ./etcdctl --endpoints https://127.0.0.1:2379 --cert /var/lib/pd-tls/tls.crt --key /var/lib/pd-tls/tls.key --cacert /var/lib/pd-tls/ca.crt member update e94cfb12fa384e23 --peer-urls="https://basic-pd-0.basic-pd-peer.pingcap.svc:2380"
+        ```
+
+        Example output:
+
+        ```shell
+        Member e94cfb12fa384e23 updated in cluster 32ab5936d81ad54c
+        ```
+
+    4. View the updated `peerURLs` to ensure they have been updated to the HTTPS protocol:
+
+        ```shell
+        ./etcdctl --endpoints https://127.0.0.1:2379 --cert /var/lib/pd-tls/tls.crt --key /var/lib/pd-tls/tls.key --cacert /var/lib/pd-tls/ca.crt member list
+        ```
+
+        Example output:
+
+        ```shell
+        e94cfb12fa384e23, started, basic-pd-0, https://basic-pd-0.basic-pd-peer.pingcap.svc:2380, https://basic-pd-0.basic-pd-peer.pingcap.svc:2379, false
+        ```
+
+5. If you previously scaled down the PD nodes, scale them back up to the original number.
+
+6. Wait for all Pods in the TiDB cluster to restart.
diff --git a/en/restore-data-using-tidb-lightning.md b/en/restore-data-using-tidb-lightning.md
@@ -52,7 +52,7 @@ For versions earlier than v1.1.10, you can modify `config` in `values.yaml` to s
 
 #### Configure TLS
 
-If TLS between components has been enabled on the target TiDB cluster (`spec.tlsCluster.enabled: true`), refer to [Generate certificates for components of the TiDB cluster](enable-tls-between-components.md#generate-certificates-for-components-of-the-tidb-cluster) to genereate a server-side certificate for TiDB Lightning, and configure `tlsCluster.enabled: true` in `values.yaml` to enable TLS between components.
+If TLS between components has been enabled on the target TiDB cluster (`spec.tlsCluster.enabled: true`), refer to [Generate certificates for components of the TiDB cluster](enable-tls-between-components.md#step-1-generate-certificates-for-components-of-the-tidb-cluster) to generate a server-side certificate for TiDB Lightning, and configure `tlsCluster.enabled: true` in `values.yaml` to enable TLS between components.
 
 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.
 

diff --git a/zh/enable-tls-between-components.md b/zh/enable-tls-between-components.md
@@ -1631,4 +1631,5 @@ summary: 在 Kubernetes 上如何为 TiDB 集群组件间开启 TLS。
         ```
 
 5. 如果之前进行了 PD 节点缩容，请将其扩容为原有数量。
+
 6. 等待 TiDB 集群中的所有 Pod 完成重启。
Original file line number	Diff line number	Diff line change
Expand Up		@@ -1631,4 +1631,5 @@ summary: 在 Kubernetes 上如何为 TiDB 集群组件间开启 TLS。
		```

		5. 如果之前进行了 PD 节点缩容，请将其扩容为原有数量。

		6. 等待 TiDB 集群中的所有 Pod 完成重启。