From 59e0a4661bde16ed85a05001c9885de236d1ce70 Mon Sep 17 00:00:00 2001 From: Xuecheng Zhang Date: Tue, 27 Oct 2020 16:00:09 +0800 Subject: [PATCH] zh: refine TLS docs; add a FAQ about task upgrade (#442) * zh: add a FAQ about running 1.0 task in 2.0 * *: fix heading * zh: fix code block * zh: update SSL file name as MySQL did * zh: refine some contents * zh: update wording * Update zh/enable-tls.md Co-authored-by: Keke Yi <40977455+yikeke@users.noreply.github.com> * Update zh/faq.md Co-authored-by: Keke Yi <40977455+yikeke@users.noreply.github.com> * Update zh/generate-self-signed-certificates.md Co-authored-by: Keke Yi <40977455+yikeke@users.noreply.github.com> * Update zh/manually-upgrade-dm-1.0-to-2.0.md Co-authored-by: Keke Yi <40977455+yikeke@users.noreply.github.com> * Update zh/faq.md Co-authored-by: Charlotte Liu <37295236+CharLotteiu@users.noreply.github.com> * Update zh/faq.md Co-authored-by: Charlotte Liu <37295236+CharLotteiu@users.noreply.github.com> Co-authored-by: Keke Yi <40977455+yikeke@users.noreply.github.com> Co-authored-by: Charlotte Liu <37295236+CharLotteiu@users.noreply.github.com> --- zh/enable-tls.md | 44 ++++++++++++++------- zh/faq.md | 9 +++++ zh/generate-self-signed-certificates.md | 52 +++++++++++++++---------- zh/maintain-dm-using-tiup.md | 1 + zh/manually-upgrade-dm-1.0-to-2.0.md | 4 ++ 5 files changed, 75 insertions(+), 35 deletions(-) diff --git a/zh/enable-tls.md b/zh/enable-tls.md index 961513f94..e2fcced73 100644 --- a/zh/enable-tls.md +++ b/zh/enable-tls.md @@ -17,20 +17,24 @@ summary: 了解如何为 DM 的连接开启加密传输。 推荐为 DM-master、DM-worker 分别准备一个 Server 证书，并保证可以相互验证，而 dmctl 工具则可选择共用 Client 证书。 - 有多种工具可以生成自签名证书，如 `openssl`，`easy-rsa`，`cfssl`。 + 有多种工具可以生成自签名证书，如 `openssl`，`cfssl` 及 `easy-rsa` 等基于 `openssl` 的工具。 这里提供一个使用 `openssl` 生成证书的示例：[生成自签名证书](generate-self-signed-certificates.md)。 2. 配置证书。 + > **注意：** + > + > DM-master、DM-worker 与 dmctl 三个组件可使用同一套证书。 + - DM-master 在 DM-master 配置文件或命令行参数中设置： ```toml ssl-ca = "/path/to/ca.pem" - ssl-cert = "/path/to/cert.pem" - ssl-key = "/path/to/key.pem" + ssl-cert = "/path/to/master-cert.pem" + ssl-key = "/path/to/master-key.pem" ``` - DM-worker @@ -39,8 +43,8 @@ summary: 了解如何为 DM 的连接开启加密传输。 ```toml ssl-ca = "/path/to/ca.pem" - ssl-cert = "/path/to/cert.pem" - ssl-key = "/path/to/key.pem" + ssl-cert = "/path/to/worker-cert.pem" + ssl-key = "/path/to/worker-key.pem" ``` - dmctl @@ -50,14 +54,14 @@ summary: 了解如何为 DM 的连接开启加密传输。 {{< copyable "shell-regular" >}} ```bash - ./dmctl -master-addr=127.0.0.1:8261 --ssl-ca /path/to/client-ca.pem --ssl-cert /path/to/client-cert.pem --ssl-key /path/to/client-key.pem + ./dmctl -master-addr=127.0.0.1:8261 --ssl-ca /path/to/ca.pem --ssl-cert /path/to/client-cert.pem --ssl-key /path/to/client-key.pem ``` ### 认证组件调用者身份 通常被调用者除了校验调用者提供的密钥、证书和 CA 有效性外，还需要校验调用者身份以防止拥有有效证书的非法访问者进行访问（例如：DM-worker 只能被 DM-master 访问，需阻止拥有合法证书但非 DM-master 的其他访问者访问 DM-worker）。 -如希望进行组件调用者身份认证，需要在生证书时通过 `Common Name` 标识证书使用者身份，并在被调用者配置检查证书 `Common Name` 列表时检查调用者身份。 +如希望进行组件调用者身份认证，需要在生成证书时通过 `Common Name` (CN) 标识证书使用者身份，并在被调用者配置检查证书 `Common Name` 列表时检查调用者身份。 - DM-master @@ -79,6 +83,8 @@ summary: 了解如何为 DM 的连接开启加密传输。 DM-master、DM-worker 和 dmctl 都会在每次新建相互通讯的连接时重新读取当前的证书和密钥文件内容，实现证书和密钥的重加载。 +当 `ssl-ca`、`ssl-cert` 或 `ssl-key` 的文件内容更新后，可通过重启 DM 组件使其重新加载证书与密钥内容并重新建立连接。 + ## DM 组件与上下游数据库之间的连接开启加密传输 本节介绍如何为 DM 组件与上下游数据库之间的连接开启加密传输。 @@ -87,26 +93,34 @@ DM-master、DM-worker 和 dmctl 都会在每次新建相互通讯的连接时重 1. 配置上游数据库，启用加密连接支持并设置 Server 证书，具体可参考 [Using encrypted connections](https://dev.mysql.com/doc/refman/5.7/en/using-encrypted-connections.html) -2. 在 source 配置文件中设置 Client 证书： +2. 在 source 配置文件中设置 MySQL Client 证书： + + > **注意：** + > + > 请确保所有 DM-master 与 DM-worker 组件能通过指定路径读取到证书与密钥文件的内容。 ```yaml from: security: - ssl-ca: "/path/to/client-ca.pem" - ssl-cert: "/path/to/client-cert.pem" - ssl-key: "/path/to/client-key.pem" + ssl-ca: "/path/to/mysql-ca.pem" + ssl-cert: "/path/to/mysql-client-cert.pem" + ssl-key: "/path/to/mysql-client-key.pem" ``` ### 为下游 TiDB 连接开启加密传输 1. 配置下游 TiDB 启用加密连接支持，具体可参考 [配置 TiDB 启用加密连接支持](https://docs.pingcap.com/zh/tidb/stable/enable-tls-between-clients-and-servers#配置-tidb-启用加密连接支持) -2. 在 task 配置文件中设置 Client 证书： +2. 在 task 配置文件中设置 TiDB Client 证书： + + > **注意：** + > + > 请确保所有 DM-master 与 DM-worker 组件能通过指定路径读取到证书与密钥文件的内容。 ```yaml target-database: security: - ssl-ca: "/path/to/client-ca.pem" - ssl-cert: "/path/to/client-cert.pem" - ssl-key: "/path/to/client-key.pem" + ssl-ca: "/path/to/tidb-ca.pem" + ssl-cert: "/path/to/tidb-client-cert.pem" + ssl-key: "/path/to/tidb-client-key.pem" ``` diff --git a/zh/faq.md b/zh/faq.md index d9d4cad6b..58e4bf6e8 100644 --- a/zh/faq.md +++ b/zh/faq.md @@ -110,3 +110,12 @@ DM 在最后 `rename ghost_table to origin table` 的步骤会把内存的 DDL - 任务配置文件中的配置项 `target-database.max-allowed-packet`（详情参见 [DM 任务完整配置文件介绍](task-configuration-file-full.md)） 设置为比默认 67108864 (64M) 更大的值。详见 [Loader 解决方案](https://docs.pingcap.com/zh/tidb/stable/loader-overview#解决方案)。 + +## 2.0 集群运行 1.0 已有数据迁移任务时报错 `Error 1054: Unknown column 'binlog_gtid' in 'field list'` + +在 DM 2.0 中，为 checkpoint 等元信息表引入了更多的字段。如果在 2.0 中，通过 `start-task` 直接使用 1.0 集群的任务配置文件从增量复制阶段继续运行，则会出现 `Error 1054: Unknown column 'binlog_gtid' in 'field list'` 错误。 + +对于此错误，可使用以下任一方式进行处理： + +- [使用 TiUP 将 DM 1.0 集群导入到全新的 2.0 集群](maintain-dm-using-tiup.md#导入-dm-ansible-部署的-dm-10-集群并升级)。 +- [手动将 DM 1.0 的数据迁移任务导入到 2.0 集群](manually-upgrade-dm-1.0-to-2.0.md)。 diff --git a/zh/generate-self-signed-certificates.md b/zh/generate-self-signed-certificates.md index 4b3e23366..01da7c539 100644 --- a/zh/generate-self-signed-certificates.md +++ b/zh/generate-self-signed-certificates.md @@ -36,34 +36,34 @@ apt install openssl yum install openssl ``` -也可以参考 OpenSSL 官方的[下载文档](https://www.openssl.org/source/) 进行安装。 +也可以参考 OpenSSL 官方的[下载文档](https://www.openssl.org/source/)进行安装。 ## 生成 CA 证书 CA 的作用是签发证书。实际情况中，请联系你的管理员签发证书或者使用信任的 CA 机构。CA 会管理多个证书对，这里只需生成原始的一对证书，步骤如下： -1. 生成 root 密钥： +1. 生成 CA 密钥： {{< copyable "shell-regular" >}} ```bash - openssl genrsa -out root.key 4096 + openssl genrsa -out ca-key.pem 4096 ``` -2. 生成 root 证书： +2. 生成 CA 证书： {{< copyable "shell-regular" >}} ```bash - openssl req -new -x509 -days 1000 -key root.key -out root.crt + openssl req -new -x509 -days 1000 -key ca-key.pem -out ca.pem ``` -3. 验证 root 证书： +3. 验证 CA 证书： {{< copyable "shell-regular" >}} ```bash - openssl x509 -text -in root.crt -noout + openssl x509 -text -in ca.pem -noout ``` ## 签发各个组件的证书 @@ -83,7 +83,7 @@ CA 的作用是签发证书。实际情况中，请联系你的管理员签发 {{< copyable "shell-regular" >}} ```bash - openssl genrsa -out master.key 2048 + openssl genrsa -out master-key.pem 2048 ``` 2. 拷贝一份 OpenSSL 的配置模板文件。 @@ -102,7 +102,7 @@ CA 的作用是签发证书。实际情况中，请联系你的管理员签发 find / -name openssl.cnf ``` -3. 编辑 `openssl.cnf`，在 `[ req ]` 字段下加入 `req_extensions = v3_req`，然后在 `[ v3_req ]` 字段下加入 `subjectAltName = @alt_names`。最后新建一个字段，并编辑 SAN 的信息： +3. 编辑 `openssl.cnf`，在 `[ req ]` 字段下加入 `req_extensions = v3_req`，然后在 `[ v3_req ]` 字段下加入 `subjectAltName = @alt_names`。最后新建一个字段，根据前述的集群拓扑并编辑 `Subject Alternative Name` (SAN) 的信息： ``` [ alt_names ] @@ -112,12 +112,22 @@ CA 的作用是签发证书。实际情况中，请联系你的管理员签发 IP.4 = 172.16.10.13 ``` -4. 保存 `openssl.cnf` 文件后，生成证书请求文件（在这一步也可以为该证书指定 Common Name，其作用是让服务端验证接入的客户端的身份，各个组件默认不会开启验证，需要在配置文件中启用该功能才生效）： + 目前支持以下 SAN 检查项： + + - `IP` + - `DNS` + - `URI` + + > **注意：** + > + > 如果要使用 `0.0.0.0` 等特殊 IP 用于连接通讯，也需要将其加入到 `alt_names` 中。 + +4. 保存 `openssl.cnf` 文件后，生成证书请求文件（在这一步中提供 `Common Name (e.g. server FQDN or YOUR name) []:` 输入时，可以为该证书指定 Common Name (CN)，如 `dm`。其作用是让服务端验证接入的客户端的身份，各个组件默认不会开启验证，需要在配置文件中启用该功能才生效）： {{< copyable "shell-regular" >}} ```bash - openssl req -new -key master.key -out master.csr -config openssl.cnf + openssl req -new -key master-key.pem -out master-cert.pem -config openssl.cnf ``` 5. 签发生成证书： @@ -125,7 +135,7 @@ CA 的作用是签发证书。实际情况中，请联系你的管理员签发 {{< copyable "shell-regular" >}} ```bash - openssl x509 -req -days 365 -CA root.crt -CAkey root.key -CAcreateserial -in master.csr -out master.crt -extensions v3_req -extfile openssl.cnf + openssl x509 -req -days 365 -CA ca.pem -CAkey ca-key.pem -CAcreateserial -in master-cert.pem -out master-cert.pem -extensions v3_req -extfile openssl.cnf ``` 6. 验证证书携带 SAN 字段信息（可选）： @@ -133,18 +143,20 @@ CA 的作用是签发证书。实际情况中，请联系你的管理员签发 {{< copyable "shell-regular" >}} ```bash - openssl x509 -text -in master.crt -noout + openssl x509 -text -in master-cert.pem -noout ``` 7. 确认在当前目录下得到如下文件： ``` - root.crt - master.crt - master.key + ca.pem + master-cert.pem + master-key.pem ``` -为 DM-worker 组件签发证书的过程类似，此文档不再赘述。 +> **注意：** +> +> 为 DM-worker 组件签发证书的过程类似，此文档不再赘述。 ### 为 dmctl 签发证书 @@ -155,7 +167,7 @@ CA 的作用是签发证书。实际情况中，请联系你的管理员签发 {{< copyable "shell-regular" >}} ```bash - openssl genrsa -out client.key 2048 + openssl genrsa -out client-key.pem 2048 ``` 2. 生成证书请求文件（在这一步也可以为该证书指定 Common Name，其作用是让服务端验证接入的客户端的身份，默认不会开启对各个组件的验证，需要在配置文件中启用该功能才生效） @@ -163,7 +175,7 @@ CA 的作用是签发证书。实际情况中，请联系你的管理员签发 {{< copyable "shell-regular" >}} ```bash - openssl req -new -key client.key -out client.csr + openssl req -new -key client-key.pem -out client-cert.pem ``` 3. 签发生成证书： @@ -171,5 +183,5 @@ CA 的作用是签发证书。实际情况中，请联系你的管理员签发 {{< copyable "shell-regular" >}} ```bash - openssl x509 -req -days 365 -CA root.crt -CAkey root.key -CAcreateserial -in client.csr -out client.crt + openssl x509 -req -days 365 -CA ca.pem -CAkey ca-key.pem -CAcreateserial -in client-cert.pem -out client-cert.pem ``` diff --git a/zh/maintain-dm-using-tiup.md b/zh/maintain-dm-using-tiup.md index 091365ded..883e23a1b 100644 --- a/zh/maintain-dm-using-tiup.md +++ b/zh/maintain-dm-using-tiup.md @@ -262,6 +262,7 @@ tiup dm patch prod-cluster /tmp/dm--hotfix.tar.gz -N 172.16.4.5:8261 > - TiUP 不支持导入 1.0 集群中的 DM Portal 组件。 > - 导入前请先停止原集群。 > - 仅支持导入到 v2.0.0-rc.2 或更高版本。 +> - `import` 命令用于将 DM 1.0 集群导入到全新的 2.0 集群。如果需要将数据迁移任务导入到已有的 2.0 集群，请参考 [TiDB Data Migration 1.0.x 到 2.0.x 手动升级](manually-upgrade-dm-1.0-to-2.0.md)。 > - 部分组件生成的部署目录会跟原集群不一样，具体可以使用 `display` 命令查看。 > - 导入前运行 `tiup update --self && tiup update dm` 确认升级 TiUP DM 组件到最新版本。 > - 导入后集群中仅会有一个 DM-master 节点，可参考[扩容节点](#扩容节点)对 DM-master 进行扩容。 diff --git a/zh/manually-upgrade-dm-1.0-to-2.0.md b/zh/manually-upgrade-dm-1.0-to-2.0.md index 4ad4e3b13..a585273a8 100644 --- a/zh/manually-upgrade-dm-1.0-to-2.0.md +++ b/zh/manually-upgrade-dm-1.0-to-2.0.md @@ -105,6 +105,10 @@ from: ## 第 2 步：部署 v2.0.x 集群 +> **注意：** +> +> 如果已有其他可用的 v2.0.x 集群，可跳过此步。 + [使用 TiUP](deploy-a-dm-cluster-using-tiup.md) 按所需要节点数部署新的 v2.0.x 集群。 ## 第 3 步：下线 v1.0.x 集群