diff --git a/docs/designs/backup-and-restore-design.md b/docs/designs/backup-and-restore-design.md index e1ad84538..6a3ea9ab1 100644 --- a/docs/designs/backup-and-restore-design.md +++ b/docs/designs/backup-and-restore-design.md @@ -27,9 +27,9 @@ When users create a DocumentDB Backup resource, the operator automatically creat **Why not use CNPG Backup directly?** -In this phase, our Backup resource acts as a wrapper around CNPG Backup. We maintain our own CRD to support future enhancements: -- **Next phase:** Multi-region backup support -- **Future:** Multi-node backup capabilities +Our Backup resource provides capabilities beyond CNPG's Backup: +- **Retention management** — each backup is assigned an expiration time and the operator automatically deletes it once it expires. The retention period can be set per-backup, per-schedule, or per-cluster (`retentionDays`), and defaults to 30 days. Backups are retained according to this period even after the cluster is deleted, so you can still restore from a deleted cluster. +- **Multi-region backup support** — in a multi-region deployment the operator backs up only the region that currently holds the primary role, skips requests against standby regions, and automatically follows the primary across failovers (site-swap). See the [Backups in multi-region deployments](../operator-public-documentation/preview/operations/backup-and-restore.md#backups-in-multi-region-deployments) user guide. ### Creating On-Demand Backups diff --git a/docs/operator-public-documentation/preview/operations/backup-and-restore.md b/docs/operator-public-documentation/preview/operations/backup-and-restore.md index 8bb574810..4413f0571 100644 --- a/docs/operator-public-documentation/preview/operations/backup-and-restore.md +++ b/docs/operator-public-documentation/preview/operations/backup-and-restore.md @@ -19,6 +19,7 @@ Key characteristics: - **VolumeSnapshot-based** — backups use the [CSI (Container Storage Interface)](https://kubernetes.io/docs/concepts/storage/volumes/#csi) driver's snapshot capability, so they are fast and storage-efficient. - **Primary-only** — the operator always targets the primary instance for backups. +- **Multi-region aware** — in a multi-region deployment the operator backs up only the region that is currently primary; requests against a standby region are skipped. See [Backups in multi-region deployments](#backups-in-multi-region-deployments). - **Namespace-scoped** — `Backup` and `ScheduledBackup` resources must reside in the same namespace as the `DocumentDB` cluster. - **Retention-managed** — expired backups are automatically deleted by the operator. @@ -210,6 +211,44 @@ Once the status shows `Cluster in healthy state`, connect and verify your data. For additional recovery options (including PV-based recovery), see [Restore a Deleted DocumentDB Cluster](restore-deleted-cluster.md). +## Backups in multi-region deployments + +In a [multi-region deployment](../multi-region-deployment/overview.md), a single DocumentDB cluster spans multiple regions — one region is the **primary** and the others are **standby** replicas. Each region runs its own operator, and **an operator only acts on `Backup` and `ScheduledBackup` resources in its own Kubernetes cluster — there is no cross-cluster routing.** Apart from that, backups behave exactly as in a single-region cluster. + +### What you need to do + +Make sure the `Backup` or `ScheduledBackup` exists in the cluster that currently holds the **primary** role. You have two options: + +- **Apply it directly** to the current primary cluster, or +- **Propagate it to every member cluster** (for example, via [KubeFleet](../multi-region-deployment/overview.md#managed-fleet-orchestration)). The primary-region operator runs the backup while standby-region operators skip it, so the same resource is safe to define identically in every region — including after a failover. + +### Region behavior at a glance + +| Region role | Operator behavior | Backup `Phase` | +|-------------|-------------------|----------------| +| **Primary** | Takes the VolumeSnapshot | `completed` | +| **Standby** | Skips it, with the message *"Backups can only be created from the primary cluster"* (not an error) | `skipped` | +| **Promotion in progress** | Defers the backup and retries until the new primary endpoint is ready (not an error) | pending → `completed` | + +**Failover (site-swap) is handled automatically.** When the primary role moves to another region (planned or unplanned), subsequent backups are taken from the newly promoted primary. A backup requested while promotion is still in progress is deferred and retried once the primary endpoint is ready — it is never failed for this reason. + +### Verify which backups ran + +List the backups and check the `PHASE` column to see which region took the snapshot and which skipped: + +```bash +kubectl get backups -n +# NAME CLUSTER PHASE ... +# backup-example documentdb-preview completed # taken on the primary region +# backup-example documentdb-preview skipped # standby region, safely skipped +``` + +!!! tip "Scheduled backups across regions" + + Define your `ScheduledBackup` in the same namespace as the DocumentDB cluster, and make sure it exists in the current primary cluster — either apply it there directly or propagate it to every member cluster (for example, via KubeFleet). Because standby regions skip backups rather than erroring, a propagated schedule keeps producing backups from whichever region is primary — including after a failover — with no manual reconfiguration. + +For planned and unplanned failover steps, see [Failover procedures](../multi-region-deployment/failover-procedures.md). + ## Backup Retention Policy Each backup receives an expiration time. After expiration, the operator deletes it automatically. You can define the retention period at multiple levels: