From ba78f63a8571976d4a24b18be071f9a5f85329b3 Mon Sep 17 00:00:00 2001 From: Wenqi Mou Date: Sat, 14 Sep 2024 12:50:02 -0400 Subject: [PATCH 01/13] add doc for log backup encryption --- br/br-pitr-manual.md | 95 +++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 94 insertions(+), 1 deletion(-) diff --git a/br/br-pitr-manual.md b/br/br-pitr-manual.md index aaa053447d3b..93ab8022db51 100644 --- a/br/br-pitr-manual.md +++ b/br/br-pitr-manual.md @@ -6,6 +6,18 @@ aliases: ['/zh/tidb/dev/br-log-command-line/'] # TiDB 日志备份与 PITR 命令行手册 +目录： +- [日志备份命令行介绍](#日志备份命令行介绍) + - [启动日志备份](#启动日志备份) + - [备份数据加密](#备份数据加密) + - [查询日志备份任务](#查询日志备份任务) + - [暂停和恢复日志备份任务](#暂停和恢复日志备份任务) + - [停止和重启日志备份任务](#停止和重启日志备份任务) + - [清理日志备份数据](#清理日志备份数据) + - [查看备份数据元信息](#查看备份数据元信息) +- [恢复到指定时间点 PITR](#恢复到指定时间点-pitr) + - [恢复加密的快照备份数据](#恢复加密的快照备份数据) + 本文介绍 TiDB 日志备份和 PITR (Point-in-time recovery) 命令行。 如果你想了解如何进行日志备份与 PITR，可以参考以下教程： @@ -38,7 +50,7 @@ Available Commands: 各个子命令的作用如下： - `tiup br log start`：启动一个日志备份任务 -- `tiup br log status`：查询日志备份任务状态 +- `tiup br log status`：查询日志备份任务��态 - `tiup br log pause`：暂停日志备份任务 - `tiup br log resume`：重启暂停的备份任务 - `tiup br log stop`：停止备份任务，并删除任务元信息 @@ -87,6 +99,59 @@ tiup br log start --task-name=pitr --pd="${PD_IP}:2379" \ --storage='s3://backup-101/logbackup?access-key=${access-key}&secret-access-key=${secret-access-key}"' ``` +### 日志数据备份加密 + +> **警告：** +> +> 当前该功能为实验特性，不建议在生产环境中使用。 + +BR 支持在上传到备份存储之前对日志备份数据进行加密。 + +自 TiDB v8.4.0 起，你可以通过直接传入数据密钥配置参数来加密日志备份数据，类似于快照备份加密： + +- `--log.crypter.method`：加密算法，支持 `aes128-ctr`、`aes192-ctr` 和 `aes256-ctr` 三种算法，缺省值为 `plaintext`，表示不加密 +- `--log.crypter.key`：加密密钥，十六进制字符串格式，`aes128-ctr` 对应 128 位（16 字节）密钥长度，`aes192-ctr` 为 24 字节，`aes256-ctr` 为 32 字节 +- `--log.crypter.key-file`：密钥文件，可直接将存放密钥的文件路径作为参数传入，此时 `log.crypter.key` 不需要配置 + +备份加密的示例如下： + +```shell +tiup br log start \ + --task-name=pitr-with-encryption + --pd ${PD_IP}:2379 \ + --storage "s3://${BACKUP_COLLECTION_ADDR}/snapshot-${DATE}?access-key=${AWS_ACCESS_KEY}&secret-access-key=${AWS_SECRET_ACCESS_KEY}" \ + --log.crypter.method aes128-ctr \ + --log.crypter.key 0123456789abcdef0123456789abcdef +``` + +然而，在更严格的加密场景中，你可能不希望在命令行中传入固定的加密密钥。相反，你可以使用基于主密钥的加密系统来管理加密密钥。基于主密钥的加密使用不同的数据密钥来加密不同的日志备份文件，并且支持主密钥轮换。 + +--master-key-crypter-method：用于加密日志备份文件的加密算法，可以是 aes128-ctr、aes192-ctr 或 aes256-ctr。默认值为 plaintext。 +--master-key：主密钥配置。可以是基于本地磁盘的主密钥或基于云 KMS 的主密钥。 + +使用本地磁盘主密钥加密： +```shell +tiup br log start \ + --task-name=pitr-with-encryption \ + --pd ${PD_IP}:2379 \ + --storage "s3://${BACKUP_COLLECTION_ADDR}/snapshot-${DATE}?access-key=${AWS_ACCESS_KEY}&secret-access-key=${AWS_SECRET_ACCESS_KEY}" \ + --master-key-crypter-method aes128-ctr \ + --master-key "local:///path/to/master.key" +``` +或者使用云 KMS 加密： +```shell +... + --master-key "aws-kms:///${AWS_KMS_KEY_ID}?AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY}&AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY}®ION=${AWS_REGION}" +``` +```shell +... + --master-key "gcp-kms:///projects/$GCP_PROJECT_ID/locations/$GCP_LOCATION/keyRings/$GCP_KEY_RING/cryptoKeys/$GCP_KEY_NAME?AUTH=specified&CREDENTIALS=$GCP_CREDENTIALS_PATH" +``` +> **注意：** +> +> - 密钥丢失，备份的数据将无法恢复到集群中。 +> - 加密功能需在 br 工具和 TiDB 集群都不低于 v8.4.0 的版本上使用，且加密日志备份得到的数据无法在低于 v8.4.0 版本的集群上恢复。 + ### 查询日志备份任务 执行 `tiup br log status` 命令，你可以查询日志备份任务状态。 @@ -399,3 +464,31 @@ Restore KV Files <-------------------------------------------------------------- > - 第一次恢复集群时，必须指定全量快照数据，否则可能因为 Table ID 重写规则，导致部分新创建的表数据不正确。详情可见此 GitHub issue [#54418](https://github.com/pingcap/tidb/issues/54418)。 > - 不支持重复恢复某段时间区间的日志，如多次重复恢复 `[t1=10, t2=20)` 区间的日志数据，可能会造成恢复后的数据不正确。 > - 多次恢复不同时间区间的日志时，需保证恢复日志的连续性。如先后恢复 `[t1, t2)`、`[t2, t3)` 和 `[t3, t4)` 三个区间的日志可以保证正确性，而在恢复 `[t1, t2)` 后跳过 `[t2, t3)` 直接恢复 `[t3, t4)` 的区间可能导致恢复之后的数据不正确。 + +### 恢复加密的日志备份数据 + +> **警告：** +> +> 当前该功能为实验特性，不建议在生产环境中使用。 + +在对数据进行加密备份后，恢复操作需要传入相应的解密参数。如果解密算法或密钥不正确，则无法恢复数据。解密参数需要与加密时使用的参数一致。解密恢复的示例如下： + +```shell +tiup br restore point --pd="${PD_IP}:2379" +--storage='s3://backup-101/logbackup?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}"' +--full-backup-storage='s3://backup-101/snapshot-202205120000?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}"' +--crypter.method aes128-ctr +--crypter.key 0123456789abcdef0123456789abcdef +--log.crypter.method aes128-ctr +--log.crypter.key 0123456789abcdef0123456789abcdef +``` +如果你使用主密钥加密进行日志备份，则可以使用以下命令： +```shell +tiup br restore point --pd="${PD_IP}:2379" +--storage='s3://backup-101/logbackup?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}"' +--full-backup-storage='s3://backup-101/snapshot-202205120000?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}"' +--crypter.method aes128-ctr +--crypter.key 0123456789abcdef0123456789abcdef +--master-key-crypter-method aes128-ctr +--master-key "local:///path/to/master.key" +``` \ No newline at end of file From ae3fbb163e6bb6543126275b1c98bf17ddb06baf Mon Sep 17 00:00:00 2001 From: Wenqi Mou Date: Sat, 14 Sep 2024 12:54:40 -0400 Subject: [PATCH 02/13] fix typo --- br/br-pitr-manual.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/br/br-pitr-manual.md b/br/br-pitr-manual.md index 93ab8022db51..747eaa548b1d 100644 --- a/br/br-pitr-manual.md +++ b/br/br-pitr-manual.md @@ -50,7 +50,7 @@ Available Commands: 各个子命令的作用如下： - `tiup br log start`：启动一个日志备份任务 -- `tiup br log status`：查询日志备份任务��态 +- `tiup br log status`：查询日志备份任务状态 - `tiup br log pause`：暂停日志备份任务 - `tiup br log resume`：重启暂停的备份任务 - `tiup br log stop`：停止备份任务，并删除任务元信息 From c1946ab60dbdff173e4eac74bed283bc80ea3f13 Mon Sep 17 00:00:00 2001 From: Wenqi Mou Date: Sat, 14 Sep 2024 14:58:21 -0400 Subject: [PATCH 03/13] fix format --- br/br-pitr-manual.md | 23 +++++++++++++++-------- 1 file changed, 15 insertions(+), 8 deletions(-) diff --git a/br/br-pitr-manual.md b/br/br-pitr-manual.md index 747eaa548b1d..6276d97d055f 100644 --- a/br/br-pitr-manual.md +++ b/br/br-pitr-manual.md @@ -8,15 +8,15 @@ aliases: ['/zh/tidb/dev/br-log-command-line/'] 目录： - [日志备份命令行介绍](#日志备份命令行介绍) - - [启动日志备份](#启动日志备份) - - [备份数据加密](#备份数据加密) - - [查询日志备份任务](#查询日志备份任务) - - [暂停和恢复日志备份任务](#暂停和恢复日志备份任务) - - [停止和重启日志备份任务](#停止和重启日志备份任务) - - [清理日志备份数据](#清理日志备份数据) - - [查看备份数据元信息](#查看备份数据元信息) + - [启动日志备份](#启动日志备份) + - [日志数据备份加密](#日志数据备份加密) + - [查询日志备份任务](#查询日志备份任务) + - [暂停和恢复日志备份任务](#暂停和恢复日志备份任务) + - [停止和重启日志备份任务](#停止和重启日志备份任务) + - [清理日志备份数据](#清理日志备份数据) + - [查看备份数据元信息](#查看备份数据元信息) - [恢复到指定时间点 PITR](#恢复到指定时间点-pitr) - - [恢复加密的快照备份数据](#恢复加密的快照备份数据) + - [恢复加密的日志备份数据](#恢复加密的日志备份数据) 本文介绍 TiDB 日志备份和 PITR (Point-in-time recovery) 命令行。 @@ -130,6 +130,7 @@ tiup br log start \ --master-key：主密钥配置。可以是基于本地磁盘的主密钥或基于云 KMS 的主密钥。 使用本地磁盘主密钥加密： + ```shell tiup br log start \ --task-name=pitr-with-encryption \ @@ -138,15 +139,19 @@ tiup br log start \ --master-key-crypter-method aes128-ctr \ --master-key "local:///path/to/master.key" ``` + 或者使用云 KMS 加密： + ```shell ... --master-key "aws-kms:///${AWS_KMS_KEY_ID}?AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY}&AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY}®ION=${AWS_REGION}" ``` + ```shell ... --master-key "gcp-kms:///projects/$GCP_PROJECT_ID/locations/$GCP_LOCATION/keyRings/$GCP_KEY_RING/cryptoKeys/$GCP_KEY_NAME?AUTH=specified&CREDENTIALS=$GCP_CREDENTIALS_PATH" ``` + > **注意：** > > - 密钥丢失，备份的数据将无法恢复到集群中。 @@ -482,7 +487,9 @@ tiup br restore point --pd="${PD_IP}:2379" --log.crypter.method aes128-ctr --log.crypter.key 0123456789abcdef0123456789abcdef ``` + 如果你使用主密钥加密进行日志备份，则可以使用以下命令： + ```shell tiup br restore point --pd="${PD_IP}:2379" --storage='s3://backup-101/logbackup?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}"' From 9d2ff0b61cdfbf6420741321838dd9bf098d40bd Mon Sep 17 00:00:00 2001 From: Wenqi Mou Date: Sat, 14 Sep 2024 15:06:31 -0400 Subject: [PATCH 04/13] one more format fix --- br/br-pitr-manual.md | 1 + 1 file changed, 1 insertion(+) diff --git a/br/br-pitr-manual.md b/br/br-pitr-manual.md index 6276d97d055f..932f97d395d4 100644 --- a/br/br-pitr-manual.md +++ b/br/br-pitr-manual.md @@ -7,6 +7,7 @@ aliases: ['/zh/tidb/dev/br-log-command-line/'] # TiDB 日志备份与 PITR 命令行手册 目录： + - [日志备份命令行介绍](#日志备份命令行介绍) - [启动日志备份](#启动日志备份) - [日志数据备份加密](#日志数据备份加密) From 475573411709eceb107f37812b11253acb56983a Mon Sep 17 00:00:00 2001 From: Wenqi Mou Date: Thu, 19 Sep 2024 11:12:32 -0400 Subject: [PATCH 05/13] remove index --- br/br-pitr-manual.md | 13 ------------- 1 file changed, 13 deletions(-) diff --git a/br/br-pitr-manual.md b/br/br-pitr-manual.md index 932f97d395d4..ec2708024857 100644 --- a/br/br-pitr-manual.md +++ b/br/br-pitr-manual.md @@ -6,19 +6,6 @@ aliases: ['/zh/tidb/dev/br-log-command-line/'] # TiDB 日志备份与 PITR 命令行手册 -目录： - -- [日志备份命令行介绍](#日志备份命令行介绍) - - [启动日志备份](#启动日志备份) - - [日志数据备份加密](#日志数据备份加密) - - [查询日志备份任务](#查询日志备份任务) - - [暂停和恢复日志备份任务](#暂停和恢复日志备份任务) - - [停止和重启日志备份任务](#停止和重启日志备份任务) - - [清理日志备份数据](#清理日志备份数据) - - [查看备份数据元信息](#查看备份数据元信息) -- [恢复到指定时间点 PITR](#恢复到指定时间点-pitr) - - [恢复加密的日志备份数据](#恢复加密的日志备份数据) - 本文介绍 TiDB 日志备份和 PITR (Point-in-time recovery) 命令行。 如果你想了解如何进行日志备份与 PITR，可以参考以下教程： From 5a69b8d2af40e543c6f9c8467ff87e52a88e7f17 Mon Sep 17 00:00:00 2001 From: Wenqi Mou Date: Tue, 24 Sep 2024 22:41:34 -0400 Subject: [PATCH 06/13] address comments --- br/br-pitr-manual.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/br/br-pitr-manual.md b/br/br-pitr-manual.md index ec2708024857..43990c3a01fb 100644 --- a/br/br-pitr-manual.md +++ b/br/br-pitr-manual.md @@ -87,7 +87,7 @@ tiup br log start --task-name=pitr --pd="${PD_IP}:2379" \ --storage='s3://backup-101/logbackup?access-key=${access-key}&secret-access-key=${secret-access-key}"' ``` -### 日志数据备份加密 +### 加密日志备份数据 > **警告：** > From ab38bb3b398798c25d313e0d98898b0537fb4252 Mon Sep 17 00:00:00 2001 From: Wenqi Mou Date: Thu, 26 Sep 2024 10:27:20 -0400 Subject: [PATCH 07/13] address comments --- br/br-pitr-manual.md | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/br/br-pitr-manual.md b/br/br-pitr-manual.md index 43990c3a01fb..66b6a9b9d670 100644 --- a/br/br-pitr-manual.md +++ b/br/br-pitr-manual.md @@ -91,17 +91,18 @@ tiup br log start --task-name=pitr --pd="${PD_IP}:2379" \ > **警告：** > -> 当前该功能为实验特性，不建议在生产环境中使用。 +> 当前该功能为实验特性，不建议在生产环境中使用。该功能可能会在未事先通知的情况下发生变化或删除。如果发现 bug， +> 请在 GitHub 上提 [issue](https://github.com/pingcap/tidb/issues) 反馈。 BR 支持在上传到备份存储之前对日志备份数据进行加密。 -自 TiDB v8.4.0 起，你可以通过直接传入数据密钥配置参数来加密日志备份数据，类似于快照备份加密： +自 TiDB v8.4.0 起，你可以在日志备份命令中传入以下参数来加密日志备份数据，类似于[快照备份加密](/br/br-snapshot-manual.md#备份数据加密)： - `--log.crypter.method`：加密算法，支持 `aes128-ctr`、`aes192-ctr` 和 `aes256-ctr` 三种算法，缺省值为 `plaintext`，表示不加密 - `--log.crypter.key`：加密密钥，十六进制字符串格式，`aes128-ctr` 对应 128 位（16 字节）密钥长度，`aes192-ctr` 为 24 字节，`aes256-ctr` 为 32 字节 - `--log.crypter.key-file`：密钥文件，可直接将存放密钥的文件路径作为参数传入，此时 `log.crypter.key` 不需要配置 -备份加密的示例如下： +示例如下： ```shell tiup br log start \ @@ -112,10 +113,11 @@ tiup br log start \ --log.crypter.key 0123456789abcdef0123456789abcdef ``` -然而，在更严格的加密场景中，你可能不希望在命令行中传入固定的加密密钥。相反，你可以使用基于主密钥的加密系统来管理加密密钥。基于主密钥的加密使用不同的数据密钥来加密不同的日志备份文件，并且支持主密钥轮换。 +然而，在一些对安全性要求更高的场景中，你可能不希望在命令行中直接传入固定的加密密钥。为了进一步提高安全性， +你可以使用基于主密钥的加密系统来管理加密密钥。该系统会使用不同的数据密钥来加密不同的日志备份文件，并且支持主密钥轮换。 ---master-key-crypter-method：用于加密日志备份文件的加密算法，可以是 aes128-ctr、aes192-ctr 或 aes256-ctr。默认值为 plaintext。 ---master-key：主密钥配置。可以是基于本地磁盘的主密钥或基于云 KMS 的主密钥。 +`--master-key-crypter-method`：基于主密钥的加密算法，支持 `aes128-ctr`、`aes192-ctr` 和 `aes256-ctr` 三种算法，缺省值为 `plaintext`，表示不加密 +`--master-key`：主密钥配置，可以是基于本地磁盘的主密钥或基于云 KMS 的主密钥 使用本地磁盘主密钥加密： @@ -462,9 +464,13 @@ Restore KV Files <-------------------------------------------------------------- > **警告：** > -> 当前该功能为实验特性，不建议在生产环境中使用。 +> 当前该功能为实验特性，不建议在生产环境中使用。该功能可能会在未事先通知的情况下发生变化或删除。如果发现 bug， +> 请在 GitHub 上提 [issue](https://github.com/pingcap/tidb/issues) 反馈。 -在对数据进行加密备份后，恢复操作需要传入相应的解密参数。如果解密算法或密钥不正确，则无法恢复数据。解密参数需要与加密时使用的参数一致。解密恢复的示例如下： + +要恢复加密的日志备份数据，你需要在恢复命令中传入相应的解密参数。解密参数需要与加密时使用的参数一致。如果解密算法或密钥不正确，则无法恢复数据。 + +示例如下： ```shell tiup br restore point --pd="${PD_IP}:2379" @@ -476,7 +482,7 @@ tiup br restore point --pd="${PD_IP}:2379" --log.crypter.key 0123456789abcdef0123456789abcdef ``` -如果你使用主密钥加密进行日志备份，则可以使用以下命令： +如果日志备份是通过主密钥加密的，则可以使用以下命令进行解密恢复： ```shell tiup br restore point --pd="${PD_IP}:2379" From 10583b392b5d9d4bf7c9c1938209e805fd9e3d20 Mon Sep 17 00:00:00 2001 From: Wenqi Mou Date: Thu, 26 Sep 2024 10:34:20 -0400 Subject: [PATCH 08/13] line break --- br/br-pitr-manual.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/br/br-pitr-manual.md b/br/br-pitr-manual.md index 66b6a9b9d670..158eff4b3a25 100644 --- a/br/br-pitr-manual.md +++ b/br/br-pitr-manual.md @@ -113,11 +113,10 @@ tiup br log start \ --log.crypter.key 0123456789abcdef0123456789abcdef ``` -然而，在一些对安全性要求更高的场景中，你可能不希望在命令行中直接传入固定的加密密钥。为了进一步提高安全性， -你可以使用基于主密钥的加密系统来管理加密密钥。该系统会使用不同的数据密钥来加密不同的日志备份文件，并且支持主密钥轮换。 +然而，在一些对安全性要求更高的场景中，你可能不希望在命令行中直接传入固定的加密密钥。为了进一步提高安全性，你可以使用基于主密钥的加密系统来管理加密密钥。该系统会使用不同的数据密钥来加密不同的日志备份文件，并且支持主密钥轮换。 `--master-key-crypter-method`：基于主密钥的加密算法，支持 `aes128-ctr`、`aes192-ctr` 和 `aes256-ctr` 三种算法，缺省值为 `plaintext`，表示不加密 -`--master-key`：主密钥配置，可以是基于本地磁盘的主密钥或基于云 KMS 的主密钥 +`--master-key`：主密钥配置，可以是基于本地磁盘的主密钥或基于云 KMS 的主密钥 使用本地磁盘主密钥加密： From c697f1e7fa86b24830ea7dbb9418f68276c0ff96 Mon Sep 17 00:00:00 2001 From: Wenqi Mou Date: Thu, 26 Sep 2024 11:09:53 -0400 Subject: [PATCH 09/13] fix format? --- br/br-pitr-manual.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/br/br-pitr-manual.md b/br/br-pitr-manual.md index 158eff4b3a25..1b7b16fee340 100644 --- a/br/br-pitr-manual.md +++ b/br/br-pitr-manual.md @@ -116,7 +116,7 @@ tiup br log start \ 然而，在一些对安全性要求更高的场景中，你可能不希望在命令行中直接传入固定的加密密钥。为了进一步提高安全性，你可以使用基于主密钥的加密系统来管理加密密钥。该系统会使用不同的数据密钥来加密不同的日志备份文件，并且支持主密钥轮换。 `--master-key-crypter-method`：基于主密钥的加密算法，支持 `aes128-ctr`、`aes192-ctr` 和 `aes256-ctr` 三种算法，缺省值为 `plaintext`，表示不加密 -`--master-key`：主密钥配置，可以是基于本地磁盘的主密钥或基于云 KMS 的主密钥 +`--master-key`：主密钥配置，可以是基于本地磁盘的主密钥或基于云 KMS 的主密钥 使用本地磁盘主密钥加密： From 9cc6f497d135c57221d2d89aad9d89dfea76b0c8 Mon Sep 17 00:00:00 2001 From: Wenqi Mou Date: Thu, 26 Sep 2024 21:45:03 -0400 Subject: [PATCH 10/13] address comments and fix style --- br/br-pitr-manual.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/br/br-pitr-manual.md b/br/br-pitr-manual.md index 1b7b16fee340..157202139127 100644 --- a/br/br-pitr-manual.md +++ b/br/br-pitr-manual.md @@ -83,8 +83,10 @@ Global Flags: 使用示例： ```shell -tiup br log start --task-name=pitr --pd="${PD_IP}:2379" \ ---storage='s3://backup-101/logbackup?access-key=${access-key}&secret-access-key=${secret-access-key}"' +tiup br log start \ + --task-name=pitr \ + --pd="${PD_IP}:2379" \ + --storage='s3://backup-101/logbackup?access-key=${access-key}&secret-access-key=${secret-access-key}' ``` ### 加密日志备份数据 @@ -115,8 +117,8 @@ tiup br log start \ 然而，在一些对安全性要求更高的场景中，你可能不希望在命令行中直接传入固定的加密密钥。为了进一步提高安全性，你可以使用基于主密钥的加密系统来管理加密密钥。该系统会使用不同的数据密钥来加密不同的日志备份文件，并且支持主密钥轮换。 -`--master-key-crypter-method`：基于主密钥的加密算法，支持 `aes128-ctr`、`aes192-ctr` 和 `aes256-ctr` 三种算法，缺省值为 `plaintext`，表示不加密 -`--master-key`：主密钥配置，可以是基于本地磁盘的主密钥或基于云 KMS 的主密钥 +- `--master-key-crypter-method`：基于主密钥的加密算法，支持 `aes128-ctr`、`aes192-ctr` 和 `aes256-ctr` 三种算法，缺省值为 `plaintext`，表示不加密 +- `--master-key`：主密钥配置，可以是基于本地磁盘的主密钥或基于云 KMS 的主密钥 使用本地磁盘主密钥加密： From dbd1262f2e36d071d8edb56be5175e1daf381452 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Fri, 27 Sep 2024 10:09:44 +0800 Subject: [PATCH 11/13] format udpates --- br/br-pitr-manual.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/br/br-pitr-manual.md b/br/br-pitr-manual.md index 157202139127..c9a9228b8504 100644 --- a/br/br-pitr-manual.md +++ b/br/br-pitr-manual.md @@ -93,8 +93,7 @@ tiup br log start \ > **警告：** > -> 当前该功能为实验特性，不建议在生产环境中使用。该功能可能会在未事先通知的情况下发生变化或删除。如果发现 bug， -> 请在 GitHub 上提 [issue](https://github.com/pingcap/tidb/issues) 反馈。 +> 当前该功能为实验特性，不建议在生产环境中使用。如果发现 bug，请在 GitHub 上提 [issue](https://github.com/pingcap/tidb/issues) 反馈。 BR 支持在上传到备份存储之前对日志备份数据进行加密。 @@ -465,8 +464,7 @@ Restore KV Files <-------------------------------------------------------------- > **警告：** > -> 当前该功能为实验特性，不建议在生产环境中使用。该功能可能会在未事先通知的情况下发生变化或删除。如果发现 bug， -> 请在 GitHub 上提 [issue](https://github.com/pingcap/tidb/issues) 反馈。 +> 当前该功能为实验特性，不建议在生产环境中使用。如果发现 bug，请在 GitHub 上提 [issue](https://github.com/pingcap/tidb/issues) 反馈。 要恢复加密的日志备份数据，你需要在恢复命令中传入相应的解密参数。解密参数需要与加密时使用的参数一致。如果解密算法或密钥不正确，则无法恢复数据。 From ada905ed86f860818df14f42bb7a3616b9ad64d6 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Mon, 30 Sep 2024 15:35:21 +0800 Subject: [PATCH 12/13] Apply suggestions from code review Co-authored-by: Aolin --- br/br-pitr-manual.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/br/br-pitr-manual.md b/br/br-pitr-manual.md index c9a9228b8504..50ff5bc442d0 100644 --- a/br/br-pitr-manual.md +++ b/br/br-pitr-manual.md @@ -114,10 +114,10 @@ tiup br log start \ --log.crypter.key 0123456789abcdef0123456789abcdef ``` -然而，在一些对安全性要求更高的场景中，你可能不希望在命令行中直接传入固定的加密密钥。为了进一步提高安全性，你可以使用基于主密钥的加密系统来管理加密密钥。该系统会使用不同的数据密钥来加密不同的日志备份文件，并且支持主密钥轮换。 +然而，在一些对安全性要求更高的场景中，你可能不希望在命令行中直接传入固定的加密密钥。为了进一步提高安全性，你可以使用基于主密钥的加密系统来管理加密密钥。该系统会使用不同的数据密钥来加密不同的日志备份文件，并且支持主密钥轮换。你可以在日志备份命令中传入以下参数来配置基于主密钥的加密： - `--master-key-crypter-method`：基于主密钥的加密算法，支持 `aes128-ctr`、`aes192-ctr` 和 `aes256-ctr` 三种算法，缺省值为 `plaintext`，表示不加密 -- `--master-key`：主密钥配置，可以是基于本地磁盘的主密钥或基于云 KMS 的主密钥 +- `--master-key`：主密钥配置，可以是基于本地磁盘的主密钥或基于云 KMS (Key Management Service) 的主密钥 使用本地磁盘主密钥加密： @@ -130,13 +130,15 @@ tiup br log start \ --master-key "local:///path/to/master.key" ``` -或者使用云 KMS 加密： +使用 AWS KMS 加密： ```shell ... --master-key "aws-kms:///${AWS_KMS_KEY_ID}?AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY}&AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY}®ION=${AWS_REGION}" ``` +使用 Google Cloud KMS 加密： + ```shell ... --master-key "gcp-kms:///projects/$GCP_PROJECT_ID/locations/$GCP_LOCATION/keyRings/$GCP_KEY_RING/cryptoKeys/$GCP_KEY_NAME?AUTH=specified&CREDENTIALS=$GCP_CREDENTIALS_PATH" @@ -466,7 +468,6 @@ Restore KV Files <-------------------------------------------------------------- > > 当前该功能为实验特性，不建议在生产环境中使用。如果发现 bug，请在 GitHub 上提 [issue](https://github.com/pingcap/tidb/issues) 反馈。 - 要恢复加密的日志备份数据，你需要在恢复命令中传入相应的解密参数。解密参数需要与加密时使用的参数一致。如果解密算法或密钥不正确，则无法恢复数据。 示例如下： From d91bbe453923dcba187f8075059237ebe29fe920 Mon Sep 17 00:00:00 2001 From: Wenqi Mou Date: Fri, 11 Oct 2024 13:46:30 -0400 Subject: [PATCH 13/13] Apply suggestions from code review Co-authored-by: Aolin --- br/br-pitr-manual.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/br/br-pitr-manual.md b/br/br-pitr-manual.md index 50ff5bc442d0..4069b5a20fe8 100644 --- a/br/br-pitr-manual.md +++ b/br/br-pitr-manual.md @@ -133,14 +133,22 @@ tiup br log start \ 使用 AWS KMS 加密： ```shell -... +tiup br log start \ + --task-name=pitr-with-encryption \ + --pd ${PD_IP}:2379 \ + --storage "s3://${BACKUP_COLLECTION_ADDR}/snapshot-${DATE}?access-key=${AWS_ACCESS_KEY}&secret-access-key=${AWS_SECRET_ACCESS_KEY}" \ + --master-key-crypter-method aes128-ctr \ --master-key "aws-kms:///${AWS_KMS_KEY_ID}?AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY}&AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY}®ION=${AWS_REGION}" ``` 使用 Google Cloud KMS 加密： ```shell -... +tiup br log start \ + --task-name=pitr-with-encryption \ + --pd ${PD_IP}:2379 \ + --storage "s3://${BACKUP_COLLECTION_ADDR}/snapshot-${DATE}?access-key=${AWS_ACCESS_KEY}&secret-access-key=${AWS_SECRET_ACCESS_KEY}" \ + --master-key-crypter-method aes128-ctr \ --master-key "gcp-kms:///projects/$GCP_PROJECT_ID/locations/$GCP_LOCATION/keyRings/$GCP_KEY_RING/cryptoKeys/$GCP_KEY_NAME?AUTH=specified&CREDENTIALS=$GCP_CREDENTIALS_PATH" ```