Skip to content

docs: document multi-region backup behavior (#196) - #430

Open
WentingWu666666 wants to merge 4 commits into
documentdb:mainfrom
WentingWu666666:developer/wenting-multi-region-backup-docs
Open

docs: document multi-region backup behavior (#196)#430
WentingWu666666 wants to merge 4 commits into
documentdb:mainfrom
WentingWu666666:developer/wenting-multi-region-backup-docs

Conversation

@WentingWu666666

@WentingWu666666 WentingWu666666 commented Jul 23, 2026

Copy link
Copy Markdown
Collaborator

Summary

Closes #196.

Multi-region backup/restore was already implemented in #141, but the documentation was never updated (the issue tracked a "Need to update docs" follow-up). This PR documents the region-aware backup behavior for both users and maintainers.

Changes

  • operations/backup-and-restore.md
    • New "Backups in multi-region deployments" section covering:
      • primary-only backups (operator routes the snapshot to the current primary region),
      • standby-region requests are skipped, not failed ("Backups can only be created from the primary cluster"),
      • automatic site-swap/failover handling (backups follow the newly promoted primary; deferred if promotion is still in progress).
    • Added a multi-region bullet to the Overview key characteristics.
  • multi-region-deployment/setup.md — fixed a broken "Backup and restore" link (../backup-and-restore.md → ../operations/backup-and-restore.md).
  • designs/backup-and-restore-design.md — marked Multi-region backup support as implemented instead of "Next phase".

Backing implementation (already merged, for reviewer context)

  • backup_controller.go enforces replicationContext.IsPrimary() (skip on standby) and EndpointEnabled() (defer during promotion), and targets replicationContext.CNPGClusterName.
  • e2e coverage: test/e2e/tests/cluster_replication/backup_test.go (primary succeeds, replica skipped, backup after failover succeeds).

Notes

Docs-only change — no code or generated files affected.

@wentingwu000
docs: document multi-region backup behavior (documentdb#196)
43efbcd 
Multi-region backup/restore was implemented in documentdb#141 but the docs were
not updated. This documents the region-aware backup behavior for users
and maintainers:

- Add a "Backups in multi-region deployments" section to the public
  backup-and-restore guide covering primary-only backups, standby-region
  skip, and automatic site-swap/failover handling.
- Note multi-region awareness in the backup overview key characteristics.
- Fix broken backup-and-restore link in the multi-region setup guide.
- Mark multi-region backup as implemented in the design doc.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 0e57fca7-ab02-456c-aad6-6ddc4c89ba2f
Signed-off-by: Wenting Wu <wentingwu@microsoft.com>
@WentingWu666666
WentingWu666666 force-pushed the developer/wenting-multi-region-backup-docs branch from 97cabc6 to 43efbcd Compare July 23, 2026 17:19
@documentdb-triage-tool documentdb-triage-tool Bot added the documentation Improvements or additions to documentation label Jul 23, 2026
@documentdb-triage-tool

documentdb-triage-tool Bot commented Jul 23, 2026

Copy link
Copy Markdown

🤖 Auto-triaged by documentdb-triage-tool.

Applied: documentation
Project fields suggested: Component docs · Priority P3 · Effort M · Status In Progress
Confidence: 0.95 (mixed)

Reasoning

component from path globs (docs); effort from diff stats (17+2 LOC, 2 files); LLM: Docs-only PR that documents already-implemented multi-region backup behavior and fixes a broken link — no code changes, low urgency.

If a label is wrong, remove it manually and ping @patty-chow so the rules can be tuned. The bot will not re-label items that already have component labels.

@WentingWu666666
WentingWu666666 marked this pull request as ready for review August 20, 2026 17:04
Copilot AI lite review requested due to automatic review settings August 20, 2026 17:04
Copilot AI reviewed Aug 20, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Pull request overview

Updates the operator’s documentation to reflect the already-implemented multi-region backup behavior, so users and maintainers understand how backups behave across primary/standby regions and during failover.

Changes:

  • Documented multi-region backup rules (primary-only execution, standby skip semantics, failover/promotion behavior) in the public Backup/Restore guide.
  • Fixed a broken “Backup and restore” link in the multi-region setup guide.
  • Updated the backup/restore design doc to mark multi-region backup support as implemented and link to the user guide.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File Description
docs/operator-public-documentation/preview/operations/backup-and-restore.md Adds multi-region backup behavior section and highlights multi-region awareness in the overview.
docs/operator-public-documentation/preview/multi-region-deployment/setup.md Fixes the relative link to the Backup/Restore operations doc.
docs/designs/backup-and-restore-design.md Marks multi-region backup support as implemented and points to the updated user documentation.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Comment thread docs/operator-public-documentation/preview/operations/backup-and-restore.md Outdated
@WentingWu666666
WentingWu666666 marked this pull request as draft August 21, 2026 17:29
wentingwu000 and others added 2 commits August 21, 2026 14:01
@wentingwu000
docs: clarify multi-region backups require the resource on the primar…
43de583 
…y cluster

Each region runs its own operator with no cross-cluster routing; a Backup
created only on a standby cluster is skipped and no snapshot is taken. Clarify
that the resource must exist in the current primary cluster (applied directly
or propagated via KubeFleet). Also redraft the CNPG-wrapper rationale to list
retention management and multi-region support as the added capabilities.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Signed-off-by: Wenting Wu <wentingwu@microsoft.com>
@wentingwu000
docs: make multi-region backup section more scannable
c5c39dd 
Restructure the multi-region backup guidance for readability: lead with the
required user action, add an at-a-glance region-behavior table with the actual
Backup phases (completed/skipped), and add a kubectl verification example.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Signed-off-by: Wenting Wu <wentingwu@microsoft.com>
@WentingWu666666
WentingWu666666 marked this pull request as ready for review August 21, 2026 18:43
xgerman
xgerman reviewed Aug 21, 2026
View reviewed changes
Comment thread docs/designs/backup-and-restore-design.md Outdated
@wentingwu000
docs: drop CNPG wrapper implementation detail from backup design
8cbc89b 
Per review feedback, describe the DocumentDB Backup by the capabilities it
adds over CNPG's Backup rather than how it is implemented (wrapper/own CRD).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Signed-off-by: Wenting Wu <wentingwu@microsoft.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@xgerman xgerman xgerman left review comments
Copilot code review Copilot
Copilot review effort
Applies to this pull request for everyone.Learn more about Copilot code review.
Copilot left review comments
@alaye-ms alaye-ms Awaiting requested review from alaye-ms alaye-ms is a code owner
@hossain-rayhan hossain-rayhan Awaiting requested review from hossain-rayhan hossain-rayhan is a code owner

At least 2 approving reviews are required to merge this pull request.

Assignees

No one assigned

Labels

documentation Improvements or additions to documentation

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Multi region backup/restore

4 participants

@WentingWu666666 @xgerman @wentingwu000