From 232532273e91fa25f48b7b7ac95f1019b9ae9f4d Mon Sep 17 00:00:00 2001 From: Lilian Lee Date: Tue, 23 Jun 2026 18:08:35 +0800 Subject: [PATCH 1/3] Create empty translation PR From 664e7fbb96b45522db3872aa59df0d0df92f2672 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Tue, 23 Jun 2026 10:10:29 +0000 Subject: [PATCH 2/3] Auto-sync: Update English docs from Chinese PR Synced from: https://github.com/pingcap/docs-cn/pull/21469 Target PR: https://github.com/pingcap/docs/pull/23122 AI Provider: azure Co-authored-by: github-actions[bot] --- br/backup-and-restore-storages.md | 30 ++++++++++++++++++++++++++---- encryption-at-rest.md | 18 +++++++++++++++++- tikv-configuration-file.md | 16 ++++++++++++++++ 3 files changed, 59 insertions(+), 5 deletions(-) diff --git a/br/backup-and-restore-storages.md b/br/backup-and-restore-storages.md index 43e80caebc35f..0bee3e02f28ad 100644 --- a/br/backup-and-restore-storages.md +++ b/br/backup-and-restore-storages.md @@ -139,11 +139,33 @@ It is recommended that you configure access to S3 using either of the following
-You can configure the account used to access GCS by specifying the access key. If you specify the `credentials-file` parameter, the authentication is performed using the specified `credentials-file`. Besides specifying the key in the URI, the following methods are also supported: +You can configure the credentials used to access GCS in the following ways: -- BR reads the file in the path specified by the environment variable `$GOOGLE_APPLICATION_CREDENTIALS` -- BR reads the file `~/.config/gcloud/application_default_credentials.json`. -- BR obtains the credentials from the metadata server when the cluster is running in GCE or GAE. +- Method 1: Explicitly specify `credentials-file` + + - If `credentials-file` points to a Service Account JSON file, BR and TiKV access GCS using this credential. + - If TiKV uses the `gcp_v2` external storage backend, `credentials-file` can also point to the `external_account` JSON used by Google Cloud WIF. + +- Method 2: Use Application Default Credentials (ADC) + + - BR reads the file in the path specified by the environment variable `$GOOGLE_APPLICATION_CREDENTIALS`. + - BR reads the file `~/.config/gcloud/application_default_credentials.json`. + - When BR runs in GCE or GAE, it uses the credentials obtained from the metadata server. + +If you want TiKV to use GCS WIF or ADC, you need to enable the `gcp_v2` external storage backend. Starting from v8.5.7, TiKV enables the `gcp_v2` external storage backend by default. You can configure `gcp_v2` in the following ways: + +- full backup and restore: set `[backup].gcp-v2-enable` to `true` in [TiKV Configuration File Descriptions](/tikv-configuration-file.md) +- log backup: set `[log-backup].gcp-v2-enable` to `true` in [TiKV Configuration File Descriptions](/tikv-configuration-file.md) + +The default values of the preceding two configuration items are both `true`. If you disable `gcp_v2`, TiKV continues to use the legacy GCS implementation. This implementation supports only Service Account JSON and does not support using WIF directly. + +> **Note:** +> +> The GCS JSON credentials explicitly passed to `gcp_v2` support only the `service_account` and `external_account` types. If you are using the `authorized_user` JSON generated by ADC and need TiKV to access GCS directly, it is recommended to set `--send-credentials-to-tikv=false` and configure ADC on each TiKV node. Otherwise, BR might send the `authorized_user` JSON to TiKV as an explicit credential, but `gcp_v2` does not accept this type of explicit JSON. + +> **Tip:** +> +> After `gcp_v2` is enabled, if GCS JSON credentials are not explicitly provided on the TiKV side, TiKV uses the Google Default Credentials flow. Therefore, when using ADC and setting `--send-credentials-to-tikv=false`, make sure that each TiKV node itself has a usable Google credentials environment.
diff --git a/encryption-at-rest.md b/encryption-at-rest.md index d8276dad349e9..7c94f5b7f7edf 100644 --- a/encryption-at-rest.md +++ b/encryption-at-rest.md @@ -172,7 +172,23 @@ credential-file-path = "/path/to/credential.json" ``` - `key-id` specifies the key ID of the KMS CMK. -- `credential-file-path` specifies the path of the authentication credentials file, which currently supports two types of credentials: Service Account and Authentication User. If the TiKV environment is already configured with [application default credentials](https://cloud.google.com/docs/authentication/application-default-credentials), there is no need to configure `credential-file-path`. +- When `vendor = "gcp"`, `credential-file-path` specifies the path of the verification credentials file, which currently supports two types of credentials: Service Account and Authentication User. If the TiKV operating environment is already configured with [application default credentials](https://cloud.google.com/docs/authentication/application-default-credentials), there is no need to configure `credential-file-path`. + +If you need to use Workload Identity Federation (WIF) in the Google Cloud KMS scenario, use `gcp_v2` instead: + +```toml +[security.encryption.master-key] +type = "kms" +key-id = "projects/project-name/locations/global/keyRings/key-ring-name/cryptoKeys/key-name" +vendor = "gcp_v2" + +[security.encryption.master-key.gcp] +credential-file-path = "/path/to/external-account.json" +``` + +- When `vendor = "gcp_v2"`, explicit credentials support only Service Account and `external_account`. +- If you are using an `authorized_user` JSON generated by ADC, you cannot directly configure that JSON as `credential-file-path`. In this case, omit `credential-file-path` and let TiKV obtain authentication information through [application default credentials](https://cloud.google.com/docs/authentication/application-default-credentials) in the operating environment. +- The old `vendor = "gcp"` does not support using `external_account` as explicit credentials, so WIF cannot be used in this way.
diff --git a/tikv-configuration-file.md b/tikv-configuration-file.md index 2a5b2572be8bf..2f82a75dcf455 100644 --- a/tikv-configuration-file.md +++ b/tikv-configuration-file.md @@ -2427,6 +2427,14 @@ Configuration items related to BR backup. + If data is backed up to S3 and the backup file is larger than the value of this configuration item, [multipart upload](https://docs.aws.amazon.com/AmazonS3/latest/API/API_UploadPart.html) is automatically enabled. Based on the compression ratio, the backup file generated by a 96-MiB Region is approximately 10 MiB to 30 MiB. + Default value: 5MiB +### `gcp-v2-enable` New in v8.5.7 + ++ Whether to enable the `gcp_v2` external storage backend when using Google Cloud Storage (GCS) to execute full backup or restore. ++ Default value: `true` ++ When this configuration item is `true`, TiKV uses the `gcp_v2` implementation to access GCS; when this configuration item is `false`, TiKV continues to use the old GCS implementation. ++ If you need to use Google Cloud Workload Identity Federation (WIF) in full backup or restore scenarios, keep this configuration item set to `true`. ++ For information about GCS authentication methods and how to use WIF/ADC, see [Backup storage](/br/backup-and-restore-storages.md). + ## backup.hadoop ### `home` @@ -2482,6 +2490,14 @@ Configuration items related to log backup. + The temporary path to which log files are written before being flushed to external storage. + Default value: `${deploy-dir}/data/log-backup-temp` +### `gcp-v2-enable` New in v8.5.7 + ++ Whether to enable the `gcp_v2` external storage backend when using Google Cloud Storage (GCS) for log backup. ++ Default value: `true` ++ When this configuration item is `true`, TiKV uses the `gcp_v2` implementation to access GCS; when this configuration item is `false`, TiKV continues to use the old GCS implementation. ++ If you need to use Google Cloud Workload Identity Federation (WIF) in log backup scenarios, keep this configuration item set to `true`. ++ For information about GCS authentication methods and how to use WIF/ADC, see [Backup storage](/br/backup-and-restore-storages.md). + ## cdc Configuration items related to TiCDC. From d1a22e730b16b6db5e144acb21d7a40f26c25739 Mon Sep 17 00:00:00 2001 From: Lilian Lee Date: Wed, 24 Jun 2026 16:08:38 +0800 Subject: [PATCH 3/3] Apply bold formatting to one sentence --- br/backup-and-restore-storages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/br/backup-and-restore-storages.md b/br/backup-and-restore-storages.md index 0bee3e02f28ad..04fef11078008 100644 --- a/br/backup-and-restore-storages.md +++ b/br/backup-and-restore-storages.md @@ -152,7 +152,7 @@ You can configure the credentials used to access GCS in the following ways: - BR reads the file `~/.config/gcloud/application_default_credentials.json`. - When BR runs in GCE or GAE, it uses the credentials obtained from the metadata server. -If you want TiKV to use GCS WIF or ADC, you need to enable the `gcp_v2` external storage backend. Starting from v8.5.7, TiKV enables the `gcp_v2` external storage backend by default. You can configure `gcp_v2` in the following ways: +If you want TiKV to use GCS WIF or ADC, you need to enable the `gcp_v2` external storage backend. **Starting from v8.5.7, TiKV enables the `gcp_v2` external storage backend by default.** You can configure `gcp_v2` in the following ways: - full backup and restore: set `[backup].gcp-v2-enable` to `true` in [TiKV Configuration File Descriptions](/tikv-configuration-file.md) - log backup: set `[log-backup].gcp-v2-enable` to `true` in [TiKV Configuration File Descriptions](/tikv-configuration-file.md)