Skip to content

docs: add least-privilege S3 IAM policy examples for BR - #24704

Open
doc-claw-bot wants to merge 1 commit into
masterfrom
docs/s3-least-priv-policy
Open

doc-claw-bot wants to merge 1 commit into
masterfrom
docs/s3-least-priv-policy

Conversation

@doc-claw-bot

@doc-claw-bot doc-claw-bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Collaborator

What is changed, added, or deleted? (Required)

  • 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.

For details, see tips for choosing the affected versions.

  • master (the latest development version)
  • v9.0 (TiDB 9.0 versions)
  • v8.5 (TiDB 8.5 versions)
  • v8.1 (TiDB 8.1 versions)
  • v7.5 (TiDB 7.5 versions)
  • v7.1 (TiDB 7.1 versions)
  • v6.5 (TiDB 6.5 versions)

What is the related PR or file link(s)?

AI agent involvement

  • 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.

@ti-chi-bot ti-chi-bot Bot added contribution This PR is from a community contributor. missing-translation-status This PR does not have translation status info. labels Nov 17, 2026
@ti-chi-bot

ti-chi-bot Bot commented Nov 17, 2026

Copy link
Copy Markdown

[APPROVALNOTIFIER] This PR is NOT APPROVED

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:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@ti-chi-bot ti-chi-bot Bot added the size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label Nov 17, 2026
@coderabbitai

coderabbitai Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

Explain Change →

Walkthrough

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.
Additional restore write permissions
br/backup-and-restore-storages.md
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.

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Other

Suggested reviewers: leavrth, qiancai

Merge Risk: Moderate · up to 1e17b

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: Passed 4

Check name Status Explanation
Title check Passed 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 Passed 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 Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed 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.

Share

@doc-claw-bot doc-claw-bot added ONCALL Relates to documentation oncall. area/br Indicates that the Issue or PR belongs to the area of BR (Backup & Restore). type/enhancement The issue or PR belongs to an enhancement. translation/welcome Waits for a contributor to translate this PR and create a PR to the pingcap/docs-cn repository. needs-cherry-pick-release-8.5 Should cherry pick this PR to release-8.5 branch. labels Nov 17, 2026
@ti-chi-bot ti-chi-bot Bot removed the missing-translation-status This PR does not have translation status info. label Nov 17, 2026

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Actionable comments posted: 4

Review info

Run configuration

Commits

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.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)

Comment on lines +153 to +155
"Condition": {
"StringLike": {
"s3:prefix": "<prefix>/*"

Copy link
Copy Markdown

Choose a reason for hiding this comment

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.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/br Indicates that the Issue or PR belongs to the area of BR (Backup & Restore). contribution This PR is from a community contributor. needs-cherry-pick-release-8.5 Should cherry pick this PR to release-8.5 branch. ONCALL Relates to documentation oncall. size/L Denotes a PR that changes 100-499 lines, ignoring generated files. translation/welcome Waits for a contributor to translate this PR and create a PR to the pingcap/docs-cn repository. type/enhancement The issue or PR belongs to an enhancement.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant