backup: refactor some docs for easier understanding (#12338) (#12402)

pingcap · Feb 7, 2023 · 4f13623 · 4f13623
1 parent 9b9ba45
commit 4f13623
Show file tree

Hide file tree

Showing 4 changed files with 61 additions and 28 deletions.
diff --git a/br/backup-and-restore-overview.md b/br/backup-and-restore-overview.md
@@ -15,6 +15,34 @@ BR satisfies the following requirements:
 - Perform history data auditing to meet the requirements of judicial supervision.
 - Clone the production environment, which is convenient for troubleshooting, performance tuning, and simulation testing.
 
+## Before you use
+
+This section describes the prerequisites for using TiDB backup and restore, including restrictions, usage tips and compatibility issues.
+
+### Restrictions
+
+- PITR only supports restoring data to **an empty cluster**.
+- PITR only supports cluster-level restore and does not support database-level or table-level restore.
+- PITR does not support restoring the data of user tables or privilege tables from system tables.
+- BR does not support running multiple backup tasks on a cluster **at the same time**.
+- When a PITR is running, you cannot run a log backup task or use TiCDC to replicate data to a downstream cluster.
+
+### Some tips
+
+Snapshot backup:
+
+- It is recommended that you perform the backup operation during off-peak hours to minimize the impact on applications.
+- It is recommended that you execute multiple backup or restore tasks one by one. Running multiple backup tasks in parallel leads to low performance. Worse still, a lack of collaboration between multiple tasks might result in task failures and affect cluster performance.
+
+Snapshot restore:
+
+- BR uses resources of the target cluster as much as possible. Therefore, it is recommended that you restore data to a new cluster or an offline cluster. Avoid restoring data to a production cluster. Otherwise, your application will be affected inevitably.
+
+Backup storage and network configuration:
+
+- It is recommended that you store backup data to a storage system that is compatible with Amazon S3, GCS, or Azure Blob Storage.
+- You need to ensure that BR, TiKV, and the backup storage system have enough network bandwidth, and that the backup storage system can provide sufficient read and write performance (IOPS). Otherwise, they might become a performance bottleneck during backup and restore.
+
 ## Use backup and restore
 
 The way to use BR varies with the deployment method of TiDB. This document introduces how to use the br command-line tool to back up and restore TiDB cluster data in an on-premise deployment.
@@ -75,34 +103,9 @@ TiDB supports backing up data to Amazon S3, Google Cloud Storage (GCS), Azure Bl
 - [Specify backup storage in URL](/br/backup-and-restore-storages.md#url-format)
 - [Configure access privileges to backup storages](/br/backup-and-restore-storages.md#authentication)
 
-## Before you use
-
-This section describes the prerequisites for using TiDB backup and restore, including the usage tips and compatibility issues.
-
-### Some tips
-
-Snapshot backup:
-
-- It is recommended that you perform the backup operation during off-peak hours to minimize the impact on applications.
-- It is recommended that you execute multiple backup or restore operations one by one. Running backup operations in parallel leads to low performance. Worse still, lack of collaboration between multiple tasks might result in task failures and affect cluster performance.
-
-Snapshot restore:
-
-- BR uses resources of the target cluster as much as possible. Therefore, it is recommended that you restore data to a new cluster or an offline cluster. Avoid restoring data to a production cluster. Otherwise, your application might be affected. PITR only supports restoring data to an empty cluster.
-
-PITR:
-
-- You can only perform cluster-level PITR. Database-level and table-level PITR are not supported.
-- You cannot restore data in the user tables or the privilege tables.
-
-Backup storage and network configuration:
-
-- It is recommended that you store backup data to a storage system that is compatible with Amazon S3, GCS, or Azure Blob Storage.
-- You need to ensure that BR, TiKV, and the backup storage system have enough network bandwidth, and the storage system can provide sufficient read and write performance (IOPS). Otherwise, they might become a performance bottleneck during backup and restore.
-
-### Compatibility
+## Compatibility
 
-#### Compatibility with other features
+### Compatibility with other features
 
 Backup and restore might go wrong when some TiDB features are enabled or disabled. If these features are not consistently enabled or disabled during backup and restore, compatibility issues might occur.
 
@@ -114,7 +117,7 @@ Backup and restore might go wrong when some TiDB features are enabled or disable
 | Global temporary tables | | Make sure that you are using v5.3.0 or a later version of BR to back up and restore data. Otherwise, an error occurs in the definition of the backed global temporary tables. |
 | TiDB Lightning Physical Import| | If the upstream database uses the physical import mode of TiDB Lightning, data cannot be backed up in log backup. It is recommended to perform a full backup after the data import. For more information, see [When the upstream database imports data using TiDB Lightning in the physical import mode, the log backup feature becomes unavailable. Why?](/faq/backup-and-restore-faq.md#when-the-upstream-database-imports-data-using-tidb-lightning-in-the-physical-import-mode-the-log-backup-feature-becomes-unavailable-why).|
 
-#### Version compatibility
+### Version compatibility
 
 Before performing backup and restore, BR compares and checks the TiDB cluster version with its own. If there is a major-version mismatch, BR prompts a reminder to exit. To forcibly skip the version check, you can set `--check-requirements=false`. Note that skipping the version check might introduce incompatibility.
 

diff --git a/br/backup-and-restore-storages.md b/br/backup-and-restore-storages.md
@@ -8,6 +8,26 @@ aliases: ['/tidb/stable/backup-storage-S3/','/tidb/stable/backup-storage-azblob/
 
 TiDB supports storing backup data to Amazon S3, Google Cloud Storage (GCS), Azure Blob Storage, and NFS. Specifically, you can specify the URL of backup storage in the `--storage` or `-s` parameter of `br` commands. This document introduces the [URL format](#url-format) and [authentication](#authentication) of different external storage services, and [server-side encryption](#server-side-encryption).
 
+## Send credentials to TiKV
+
+| CLI parameter | Description | Default value
+|:----------|:-------|:-------|
+| `--send-credentials-to-tikv` | Controls whether to send credentials obtained by BR to TiKV. | `true`|
+
+By default, BR sends a credential to each TiKV node when using Amazon S3, GCS, or Azure Blob Storage as the storage system. This behavior simplifies the configuration and is controlled by the parameter `--send-credentials-to-tikv`(or `-c` in short).
+
+Note that this operation is not applicable to cloud environments. If you use IAM Role authorization, each node has its own role and permissions. In this case, you need to configure `--send-credentials-to-tikv=false` (or `-c=0` in short) to disable sending credentials:
+
+```bash
+./br backup full -c=0 -u pd-service:2379 --storage 's3://bucket-name/prefix'
+```
+
+If you back up or restore data using the [`BACKUP`](/sql-statements/sql-statement-backup.md) and [`RESTORE`](/sql-statements/sql-statement-restore.md) statements, you can add the `SEND_CREDENTIALS_TO_TIKV = FALSE` option:
+
+```sql
+BACKUP DATABASE * TO 's3://bucket-name/prefix' SEND_CREDENTIALS_TO_TIKV = FALSE;
+```
+
 ## URL format
 
 ### URL format description

diff --git a/br/br-pitr-guide.md b/br/br-pitr-guide.md
@@ -14,6 +14,11 @@ Before you back up or restore data using the br command-line tool (hereinafter r
 
 ### Start log backup
 
+> **Note:**
+>
+> - The following examples assume that Amazon S3 access keys and secret keys are used to authorize permissions. If IAM roles are used to authorize permissions, you need to set `--send-credentials-to-tikv` to `false`.
+> - If other storage systems or authorization methods are used to authorize permissions, adjust the parameter settings according to [Backup Storages](/br/backup-and-restore-storages.md).
+
 To start a log backup, run `br log start`. A cluster can only run one log backup task each time.
 
 ```shell

diff --git a/br/br-snapshot-guide.md b/br/br-snapshot-guide.md
@@ -17,6 +17,11 @@ Besides basic backup and restore, snapshot backup and restore also provides the
 
 ## Back up cluster snapshots
 
+> **Note:**
+>
+> - The following examples assume that Amazon S3 access keys and secret keys are used to authorize permissions. If IAM roles are used to authorize permissions, you need to set `--send-credentials-to-tikv` to `false`.
+> - If other storage systems or authorization methods are used to authorize permissions, adjust the parameter settings according to [Backup Storages](/br/backup-and-restore-storages.md).
+
 You can back up a TiDB cluster snapshot by running the `br backup full` command. Run `br backup full --help` to see the help information:
 
 ```shell