From 5146b30e7ab4cd76d5df7d14b46901387d12ea0b Mon Sep 17 00:00:00 2001 From: Wenqi Mou Date: Sat, 14 Sep 2024 12:50:02 -0400 Subject: [PATCH] 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 aaa053447d3bd..93ab8022db518 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