You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
docs: add least-privilege S3 IAM policy examples for BR - #24704
Clarify that AmazonS3FullAccess is not required when BR only needs access to the backup bucket or prefix.
Add least-privilege IAM policy JSON examples for bucket-scoped and prefix-scoped backup access.
Add matching JSON examples for read-only restore access and note when restore metadata requires additional S3 write permissions.
Which TiDB version(s) do your changes apply to? (Required)
Tips for choosing the affected version(s):
By default, CHOOSE MASTER ONLY so your changes will be applied to the next TiDB major or minor releases. If your PR involves a product feature behavior change or a compatibility change, CHOOSE THE AFFECTED RELEASE BRANCH(ES) AND MASTER.
The changes in this PR were primarily made by an AI agent on behalf of the PR author.
Do your changes match any of the following descriptions?
Delete files
Change aliases
Need modification after applied to another branch
Might cause conflicts after applied to another branch
Summary by CodeRabbit
Documentation
Clarified minimum S3 permissions for backup and read-only restore, including bucket- and prefix-scoped policy examples.
Documented additional restore permissions for checkpoint metadata and, under specified BR v8.5.5 PITR conditions, writing the ID map to an S3 log backup directory.
This pull-request has been approved by: Once this PR has been reviewed and has the lgtm label, please assign csuzhangxc for approval. For more information see the Code Review Process. Please ensure that each of them provides their approval before proceeding.
The full list of commands accepted by this bot can be found here.
Details
Needs approval from an approver in each of these files:
The S3 storage documentation separates backup and read-only restore permissions, adds bucket- and prefix-scoped IAM policy examples, and describes additional permissions for checkpoint metadata and conditional PITR ID map writes.
Changes: S3 permissions
Layer / File(s)
Summary
Scoped backup and read-only restore policies br/backup-and-restore-storages.md
The documentation distinguishes backup from read-only restore permissions and provides bucket- and prefix-scoped policy examples.
The documentation covers checkpoint metadata writes and deletes. It also specifies when PITR requires s3:PutObject to write the ID map to an S3 log backup directory.
Users who copy the prefix-scoped backup policy may see backups into an empty prefix fail with 403 Forbidden. The restore guidance also leaves out the snapshot and checkpoint locations and the trailing-slash substitution. Fix these before merging so the examples work as written.
Pre-merge checks: 4
Check name
Status
Explanation
Title check
The title names the main change: adding least-privilege S3 IAM policy examples for BR. The raw summary and PR description both describe bucket- and prefix-scoped backup policies and read-only restore …
Description check
The description covers the required 'What is changed' section with three clear bullets. It fills in the version checkboxes (master and v8.5) and lists reference links. It also marks the AI agent invol…
Linked Issues check
Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check
Check skipped because no linked issues were found for this pull request.
Full details: Title check
Explanation
The title names the main change: adding least-privilege S3 IAM policy examples for BR. The raw summary and PR description both describe bucket- and prefix-scoped backup policies and read-only restore examples in the S3 authentication docs. The title is specific and accurate.
Full details: Description check
Explanation
The description covers the required 'What is changed' section with three clear bullets. It fills in the version checkboxes (master and v8.5) and lists reference links. It also marks the AI agent involvement checkbox. The first-time contributor checklist is omitted, but the template marks that section as removable for non-first-time contributors, and the CLA checkbox is not required for this check. The description is mostly complete.
Finishing Touches
Generate unit tests (beta)
Commit to this branch
Create a new PR
Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.
Reviewing files that changed from the base of the PR and between db26e52 and 1e17bf6.
Files selected for processing: 1
br/backup-and-restore-storages.md
Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 3 remain after this review.
- Minimum privileges for TiKV and BR to access the backup directories during restore: `s3:ListBucket` and `s3:GetObject`.
- Minimum privileges for TiKV and BR to access the backup directories during a read-only restore: `s3:ListBucket` and `s3:GetObject`.
If you use IAM policies, scope them to the bucket or prefix in the `s3://bucket-name/prefix` URI used by `--storage`. If the path is the bucket root, use a bucket-scoped policy. If the path includes a folder or prefix, add an `s3:prefix` condition to `s3:ListBucket` and scope object access to that prefix.
The reason will be displayed to describe this comment to others. Learn more.
Major · Data Integrity & Integration · Quick win
Include the snapshot location in PITR policies.
PITR can use --storage for logs and --full-backup-storage for a snapshot in another prefix. A policy scoped only to --storage cannot read that snapshot. Document the required read access for both locations. (raw.githubusercontent.com)
Tools
LanguageTool
[style] ~113-~113: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...ucket root, use a bucket-scoped policy. If the path includes a folder or prefix, a...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
Minor · Functional Correctness · Quick win
Define how to substitute a trailing slash.
For s3://bucket/backup/, substituting backup/ for <prefix> produces backup//* in the policies. That does not match objects under backup/. Tell readers to omit the trailing slash when replacing <prefix>. (raw.githubusercontent.com)
Tools
LanguageTool
[style] ~113-~113: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...ucket root, use a bucket-scoped policy. If the path includes a folder or prefix, a...
The reason will be displayed to describe this comment to others. Learn more.
Major · Functional Correctness · Quick win
Document the s3:ListBucket requirement for the backup existence check.
The prefix-scoped backup policy grants s3:ListBucket only when s3:prefix matches <prefix>/*. When BR starts a backup into an empty prefix, it can check whether backupmeta already exists. S3 returns 404 for a missing object only when the caller has s3:ListBucket on the bucket. This check request has no s3:prefix value, so the conditional grant does not apply. S3 then returns 403, and BR stops the backup with that error.
Choose one of these options:
Grant s3:ListBucket on the bucket without the s3:prefix condition. The bucket-scoped policy in this section already does this. This option lets the principal list every object key in the bucket.
Keep the s3:prefix condition and state that a backup into an empty prefix can fail with 403 Forbidden during the existence check.
If BR writes checkpoint metadata to S3, add `s3:PutObject` and `s3:DeleteObject` to the restore policy. Starting from BR v8.5.5, if the target cluster does not contain `mysql.tidb_pitr_id_map` and `--checkpoint-storage` is not specified, PITR writes the ID map to the log backup directory. If that directory is in S3, add `s3:PutObject` to the restore policy. If the same IAM user or role is shared by both backup and restore, you can combine the required actions into a single policy.
The reason will be displayed to describe this comment to others. Learn more.
Major · Data Integrity & Integration · Quick win
Scope checkpoint permissions to checkpoint storage.
If --checkpoint-storage points to a different bucket or prefix, adding actions to the example restore policy still limits them to the backup resource. BR cannot write checkpoint metadata there. Specify that the checkpoint location needs its own applicable permissions and resource scope. (raw.githubusercontent.com)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
area/brIndicates that the Issue or PR belongs to the area of BR (Backup & Restore).contributionThis PR is from a community contributor.needs-cherry-pick-release-8.5Should cherry pick this PR to release-8.5 branch.ONCALLRelates to documentation oncall.size/LDenotes a PR that changes 100-499 lines, ignoring generated files.translation/welcomeWaits for a contributor to translate this PR and create a PR to the pingcap/docs-cn repository.type/enhancementThe issue or PR belongs to an enhancement.
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What is changed, added, or deleted? (Required)
AmazonS3FullAccessis not required when BR only needs access to the backup bucket or prefix.Which TiDB version(s) do your changes apply to? (Required)
Tips for choosing the affected version(s):
By default, CHOOSE MASTER ONLY so your changes will be applied to the next TiDB major or minor releases. If your PR involves a product feature behavior change or a compatibility change, CHOOSE THE AFFECTED RELEASE BRANCH(ES) AND MASTER.
For details, see tips for choosing the affected versions.
What is the related PR or file link(s)?
AI agent involvement
Do your changes match any of the following descriptions?
Summary by CodeRabbit