Skip to content

BR: update gcp_v2 storage #21469

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
JoyC-dev wants to merge 1 commit into
base: master
Choose a base branch
from
+62 −5
Open

BR: update gcp_v2 storage #21469

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 29 additions & 4 deletions br/backup-and-restore-storages.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -139,11 +139,36 @@ tiup br restore db --db test -u "${PD_IP}:2379" \
</div>
<div label="GCS" value="gcs">

配置访问 GCS 的账户可以通过指定访问密钥的方式。如果指定了 `credentials-file` 参数，将按照指定的 `credentials-file` 进行鉴权。除了在 URI 中指定密钥文件外，还支持以下方式：
配置访问 GCS 的账户可以通过以下方式：

- br 命令行工具读取位于 `$GOOGLE_APPLICATION_CREDENTIALS` 环境变量所指定路径的文件内容
- br 命令行工具读取位于 `~/.config/gcloud/application_default_credentials.json` 的文件内容
- 在 GCE 或 GAE 中运行时，从元数据服务器中获取的凭证
- 方式一：显式指定 `credentials-file`

- 如果 `credentials-file` 指向 Service Account JSON，则 BR 和 TiKV 按该凭据访问 GCS。
- 如果 TiKV 使用 `gcp_v2` 外部存储后端，则 `credentials-file` 也可以指向 Google Cloud WIF 使用的 `external_account` JSON。
Copy link
Copy Markdown
Contributor

@v01dstar v01dstar Mar 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

要加上版本信息吧。比如 “8.5.7 之后，TiKV 默认使用 gcp_v2, xxxx"

Copy link
Copy Markdown
Contributor

@v01dstar v01dstar Mar 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

因为我们目前 LTS 是 8.5。合进 master ，但不在 8.5 有可能 confuse 客户。所以这个 doc 一定是等对应 PR 进了 8.5 被 release 了之后再合


- 方式二：使用应用默认凭据 (ADC)

- br 命令行工具读取位于 `$GOOGLE_APPLICATION_CREDENTIALS` 环境变量所指定路径的文件内容
- br 命令行工具读取位于 `~/.config/gcloud/application_default_credentials.json` 的文件内容
- 在 GCE 或 GAE 中运行时，从元数据服务器中获取的凭证

> **注意：**
>
> 如果你希望在 TiKV 侧使用 GCS 的 WIF 或 ADC，需要启用 `gcp_v2` 外部存储后端：
>
> - full backup 和 restore：将 [TiKV 配置文件描述](/tikv-configuration-file.md) 中 `[backup].gcp-v2-enable` 设为 `true`
> - log backup：将 [TiKV 配置文件描述](/tikv-configuration-file.md) 中 `[log-backup].gcp-v2-enable` 设为 `true`
>
> 上述两个配置项的默认值均为 `true`。如果关闭 `gcp_v2`，TiKV 会继续使用旧的 GCS 实现；该实现只支持 Service Account JSON，不能直接使用 WIF。

> **注意：**
>
> `gcp_v2` 显式传入的 GCS JSON 凭据只支持 `service_account` 和 `external_account` 两种类型。
> 如果你使用的是 ADC 生成的 `authorized_user` JSON，并且需要让 TiKV 直接访问 GCS，建议设置 `--send-credentials-to-tikv=false`，并在每个 TiKV 节点上配置 ADC。否则，BR 可能会把 `authorized_user` JSON 作为显式凭据发送给 TiKV，而 `gcp_v2` 不接受这类显式 JSON。

> **说明：**
>
> 在启用 `gcp_v2` 后，如果 TiKV 侧未显式提供 GCS JSON 凭据，TiKV 会使用 Google Default Credentials flow。因此，在使用 ADC 且设置 `--send-credentials-to-tikv=false` 时，需要确保每个 TiKV 节点自身都具备可用的 Google 凭据环境。

</div>
<div label="Azure Blob Storage" value="azure">
Expand Down
18 changes: 17 additions & 1 deletion encryption-at-rest.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -170,7 +170,23 @@ credential-file-path = "/path/to/credential.json"
```

- `key-id` 指定 KMS CMK 的密钥 ID。
- `credential-file-path` 指向验证凭据配置文件的路径，目前支持 Service Account 和 Authentication User 这两种凭据。如果 TiKV 的运行环境已配置[应用默认凭据](https://cloud.google.com/docs/authentication/application-default-credentials?hl=zh-cn)，则无需配置 `credential-file-path`。
- 当 `vendor = "gcp"` 时，`credential-file-path` 指向验证凭据配置文件的路径，目前支持 Service Account 和 Authentication User 这两种凭据。如果 TiKV 的运行环境已配置[应用默认凭据](https://cloud.google.com/docs/authentication/application-default-credentials?hl=zh-cn)，则无需配置 `credential-file-path`。

如果你需要在 Google Cloud KMS 场景下使用 Workload Identity Federation (WIF)，请改用 `gcp_v2`：

```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"
```

- 当 `vendor = "gcp_v2"` 时，显式凭据只支持 Service Account 和 `external_account` 两种类型。
- 如果你使用的是 ADC 生成的 `authorized_user` JSON，不能把该 JSON 直接配置为 `credential-file-path`。此时应省略 `credential-file-path`，让 TiKV 在运行环境中通过[应用默认凭据](https://cloud.google.com/docs/authentication/application-default-credentials?hl=zh-cn)获取认证信息。
- 旧的 `vendor = "gcp"` 不支持把 `external_account` 作为显式凭据使用，因此无法通过该方式使用 WIF。

</div>
<div label="Azure KMS">
Expand Down
16 changes: 16 additions & 0 deletions tikv-configuration-file.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2412,6 +2412,14 @@ Raft Engine 相关的配置项。
+ TiKV 备份数据到 S3 时，如果备份文件大于该配置项的值，会自动进行[分块上传](https://docs.aws.amazon.com/zh_cn/AmazonS3/latest/API/API_UploadPart.html)。根据压缩率的不同，96 MiB Region 产生的备份文件大约在 10 MiB~30 MiB 之间。
+ 默认值：5MiB

### `gcp-v2-enable`

+ 是否在使用 Google Cloud Storage (GCS) 执行 full backup 或 restore 时启用 `gcp_v2` 外部存储后端
+ 默认值：`true`
+ 当该配置项为 `true` 时，TiKV 在访问 GCS 时会使用 `gcp_v2` 实现；当该配置项为 `false` 时，TiKV 会继续使用旧的 GCS 实现。
+ 如果你需要在 full backup 或 restore 场景下使用 Google Cloud 的 Workload Identity Federation (WIF)，需要将该配置项保持为 `true`。
+ 关于 GCS 的鉴权方式和 WIF / ADC 的使用说明，参见 [备份存储](/br/backup-and-restore-storages.md)。

## backup.hadoop

### `home`
Expand Down Expand Up @@ -2467,6 +2475,14 @@ Raft Engine 相关的配置项。
+ 日志文件存放的临时目录，日志文件预先写入临时目录，然后 flush 到外部存储中。
+ 默认值：`${deploy-dir}/data/log-backup-temp`

### `gcp-v2-enable`

+ 是否在日志备份使用 Google Cloud Storage (GCS) 时启用 `gcp_v2` 外部存储后端。
+ 默认值：`true`
+ 当该配置项为 `true` 时，TiKV 在访问 GCS 时会使用 `gcp_v2` 实现；当该配置项为 `false` 时，TiKV 会继续使用旧的 GCS 实现。
+ 如果你需要在日志备份场景下使用 Google Cloud 的 Workload Identity Federation (WIF)，需要将该配置项保持为 `true`。
+ 关于 GCS 的鉴权方式和 WIF / ADC 的使用说明，参见 [备份存储](/br/backup-and-restore-storages.md)。

## cdc

用于 TiCDC 捕捉变更数据相关的配置项。
Expand Down
Loading