From 8f27f3e7db0c10fa7528d28155153445b4e83c2b Mon Sep 17 00:00:00 2001 From: rasika-chivate <95711051+rasika-chivate@users.noreply.github.com> Date: Wed, 1 Apr 2026 12:38:39 +0530 Subject: [PATCH 1/8] 2.14.0 Release Branch --- docs/_templates/pdf_cover_page.tpl | 4 ++-- mkdocs-base.yml | 3 ++- variables.yml | 5 +++-- 3 files changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/_templates/pdf_cover_page.tpl b/docs/_templates/pdf_cover_page.tpl index 218b5f97..fa3fd03f 100644 --- a/docs/_templates/pdf_cover_page.tpl +++ b/docs/_templates/pdf_cover_page.tpl @@ -3,8 +3,8 @@

-

Backup for MongoDB 2.13.0

+

Backup for MongoDB 2.14.0

{% if config.site_description %}

{{ config.site_description }}

{% endif %} -

2.13.0 (March 3, 2026)

\ No newline at end of file +

2.14.0 (Aril 29, 2026)

\ No newline at end of file diff --git a/mkdocs-base.yml b/mkdocs-base.yml index 55f06498..bb047829 100644 --- a/mkdocs-base.yml +++ b/mkdocs-base.yml @@ -284,7 +284,8 @@ nav: - Release notes: - release-notes.md - PBM 2.x: - - "{{pbm.full_name}} 2.13.0 ({{date.2_13_0}})": release-notes/2.13.0.md + - "{{pbm.full_name}} 2.14.0 ({{date.2_14_0}})": release-notes/2.14.0.md + - release-notes/2.13.0.md - release-notes/2.12.0.md - release-notes/2.11.0.md - release-notes/2.10.0.md diff --git a/variables.yml b/variables.yml index 30aeb165..bbb63ab1 100644 --- a/variables.yml +++ b/variables.yml @@ -1,13 +1,14 @@ # PBM Variables set for HTML output # See also mkdocs.yml plugins.with-pdf.cover_subtitle and output_path -release: '2.13.0' -version: '2.13' +release: '2.14.0' +version: '2.14' year: '2026' pbm: full_name: 'Percona Backup for MongoDB' date: + 2_14_0: 2026-04-29 2_13_0: 2026-03-03 2_12_0: 2025-11-04 2_11_0: 2025-09-25 From 1c482775ee9aafafc7504a3640bb09b44a1314b2 Mon Sep 17 00:00:00 2001 From: Rasika Chivate <95711051+rasika-chivate@users.noreply.github.com> Date: Fri, 24 Apr 2026 18:08:14 +0530 Subject: [PATCH 2/8] PBM-1730 Abort restore when balancer stop fails (#361) --- .gitignore | 2 +- docs/reference/restore-options.md | 33 ++++++++++++++++++++++++++++++- 2 files changed, 33 insertions(+), 2 deletions(-) diff --git a/.gitignore b/.gitignore index 3f55cad0..4da6fc20 100644 --- a/.gitignore +++ b/.gitignore @@ -4,7 +4,7 @@ build source/ext/__pycache__ .vscode/ - +venv/ # Local Netlify folder .netlify diff --git a/docs/reference/restore-options.md b/docs/reference/restore-options.md index 5682e0be..6747acbe 100644 --- a/docs/reference/restore-options.md +++ b/docs/reference/restore-options.md @@ -46,7 +46,7 @@ The number of workers that request data chunks from the storage during the resto ### restore.maxDownloadBufferMb *Type*: int
- +*Default*: `numDownloadWorkers * downloadChunkMb * 16` MB when unspecified or set to `0` The maximum size of the in-memory buffer that is used to download files from the S3 storage. When unspecified or set to 0, the size cannot exceed the value calculated as `numDownloadWorkers * downloadChunkMb * 16` MB. By default, the number of CPU cores * 32 * 16 MB. @@ -69,3 +69,34 @@ The custom path to `mongod` binaries. When undefined, Percona Backup for MongoDB *Type*: array of strings The list of custom paths to `mongod` binaries on every node. Percona Backup for MongoDB uses the values to start the temporary instances required during physical restore. After a physical restore the database is not started automatically. + +### restore.timeouts.balancerStop + +*Type*: int
+*Default*: 0 (unlimited) + +Defines the maximum time (in seconds) that PBM waits for the balancer to stop before starting a logical restore. If set to `0` or not set (default), PBM waits indefinitely until the balancer stops. + +PBM stops the balancer to ensure data consistency during restore operations in sharded clusters. The timeout starts when the stop request is issued. If the balancer remains active after the timeout, the restore is aborted. + +```yaml +restore: + timeouts: + balancerStop: 0 +``` + +??? example "Example" + ```yaml + restore: + timeouts: + balancerStop: 60 + ``` + + In this example, PBM waits up to 60 seconds for the balancer to stop. If the balancer is still running after this period, the restore fails. + + +This is useful when you want to: + +- Prevent restore operations from waiting indefinitely +- Enforce time limits in automated workflows +- Fail fast if the balancer cannot be stopped \ No newline at end of file From f3650b9b94acf29112fb7ac39c1bfd77068c9a68 Mon Sep 17 00:00:00 2001 From: Rasika Chivate <95711051+rasika-chivate@users.noreply.github.com> Date: Tue, 28 Apr 2026 21:13:21 +0530 Subject: [PATCH 3/8] Release-notes-2.14.0 (#354) * Release-notes-2.14.0 * Update 2.14.0.md * Update 2.14.0.md * Update 2.14.0.md * Update 2.14.0.md * Update 2.14.0.md * added admo * Update 2.14.0.md * Update 2.14.0.md * Update 2.14.0.md * Update 2.14.0.md * Update 2.14.0.md * Update 2.14.0.md * Update 2.14.0.md * Update 2.14.0.md * Update 2.14.0.md * Update 2.14.0.md * Update 2.14.0.md * PBM-1167 * PBM-1167 * PBM-1638 * PBM-1639 * PBM-1653 * PBM-1703 * Update 2.14.0.md * PBM-1345 * PBM-1472 * Update 2.14.0.md * PBM-1599 * PBM-1609 * PBM-1629 * Update 2.14.0.md * Update 2.14.0.md * Update 2.14.0.md * updated the example * Update docs/release-notes/2.14.0.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update docs/release-notes/2.14.0.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update docs/release-notes/2.14.0.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update docs/release-notes/2.14.0.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update docs/release-notes/2.14.0.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update docs/release-notes/2.14.0.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update docs/release-notes/2.14.0.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update release-notes.md * Update 2.14.0.md * Update 2.14.0.md * removed PBM-1480 * Update 2.14.0.md * Update 2.14.0.md * PBM-1598 Add timeout to admin command _configsvrBalancerStop * Update backup-options.md * Update docs/reference/backup-options.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update docs/reference/backup-options.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update docs/reference/backup-options.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update docs/reference/backup-options.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update backup-options.md * format fix * Update backup-options.md * Update backup-options.md * PBM-1598: Document what value 0 means for backup.timeouts.balancerStop Agent-Logs-Url: https://github.com/percona/pbm-docs/sessions/9caa47d3-2b9b-413b-a687-bd9155dce31f Co-authored-by: rasika-chivate <95711051+rasika-chivate@users.noreply.github.com> * Update docs/reference/backup-options.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update backup-options.md * Update docs/reference/backup-options.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update pitr-physical.md * Revert "Update pitr-physical.md" This reverts commit dbb5e5980c76cbbf520ebdd84894c4ef56be366e. * PBM-1167 * Reconcile PITR oplog behavior: update sharded-cluster bullet to reflect all-nodes behavior Agent-Logs-Url: https://github.com/percona/pbm-docs/sessions/5cf9e396-42d9-49db-8902-91496dd3e247 Co-authored-by: rasika-chivate <95711051+rasika-chivate@users.noreply.github.com> * Update pitr-physical.md * Update docs/usage/pitr-physical.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update backup.timeouts.balancerStop description Clarified the behavior of the balancer timeout setting, specifying that a value of 0 allows for indefinite waiting. * Remove balancerStop timeout example from documentation Removed YAML example for balancerStop timeout in backup options. * remove PBM-1720 from rel notes * Add PBM-1721 * PBM-1721 Enhance known limitations documentation Added section on physical backups and restores, detailing limitations for MongoDB instances without authentication. Updated headings for clarity regarding MongoDB version requirements. * Update release notes for version 2.14.0 Clarified the behavior of physical restores when encountering 'Unauthorized' errors and improved the description of the issue in the release notes. * Enhance interactive confirmation for multiple commands Updated the interactive confirmation section to include additional commands and improved clarity on the confirmation process. * updated features list and a description of confirmation prompt * Fix ConcurrentStreamParts references and the description of optimized backup uploads Updated the release notes for version 2.14.0 to clarify the performance improvements for MinIO uploads and added details about the `ConcurrentStreamParts` option. * Update default value description for balancerStop Clarified default value description for balancerStop timeout. * Fix formatting of PBM CLI command options * PBM-1600 describe confirmation prompt for restore operations * PBM-1600 add an admonition that there's a confirmation prompt before running a restore command Co-authored-by: Copilot * Apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * additional fixes in formating * Apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * PBM-1600 fix the pbm restore command in multi-storage page and clarify cleanup confirmation Co-authored-by: Copilot * PBM-1638 added kmip key identifier to backup metadata (#365) * PBM-1638 extend the pbm describe-backup command Co-authored-by: Copilot * PBM-1638 - add vault to the sample output Co-authored-by: Copilot * PBM-1638 fix wrong statement that encryption key is stored, and fix 'e.g.' Co-authored-by: Copilot * Apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Fix formatting * fix table formatting * Apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * PBM-1638 improve docs Co-authored-by: Copilot * Apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * PBM-1638 minor stylistic improvements --------- Co-authored-by: Copilot Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: Radoslaw Szulgo * Fix description of highlights in 2.14.0 Co-authored-by: Copilot * Update pitr-selective.md * Fix formatting of limitation on physical restores * Update physical.md * Fix formatting for pre-requisites in pitr-selective.md * Fix formatting and update admonition in documentation * Duplicate notes in restore-selective.md * Fix formatting for "Notes" section --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: Radoslaw Szulgo Co-authored-by: Copilot --- docs/features/known-limitations.md | 7 +- docs/features/multi-storage.md | 4 +- docs/features/physical.md | 32 +-- docs/features/restore-remapping.md | 5 +- docs/reference/backup-options.md | 43 +++- docs/reference/pbm-commands.md | 217 ++++++++++++++----- docs/release-notes.md | 1 + docs/release-notes/2.14.0.md | 82 +++++++ docs/usage/delete-backup.md | 32 ++- docs/usage/pitr-physical.md | 19 +- docs/usage/pitr-selective.md | 26 ++- docs/usage/pitr-tutorial.md | 3 + docs/usage/restore-external-agent-restart.md | 9 +- docs/usage/restore-external.md | 6 + docs/usage/restore-incremental.md | 3 + docs/usage/restore-physical.md | 5 +- docs/usage/restore-selective.md | 14 +- docs/usage/restore.md | 9 + 18 files changed, 388 insertions(+), 129 deletions(-) create mode 100644 docs/release-notes/2.14.0.md diff --git a/docs/features/known-limitations.md b/docs/features/known-limitations.md index bf029642..ba603442 100644 --- a/docs/features/known-limitations.md +++ b/docs/features/known-limitations.md @@ -14,15 +14,18 @@ PBM supports various backup and restore types. Some of them have known limitatio 5. System collections in ``admin``, ``config``, and ``local`` databases cannot be backed up and restored selectively. You must make a full backup and restore to include them. 6. Selective point-in-time recovery is not supported for sharded clusters. +## Physical backups and restores +Physical restores are not supported for MongoDB instances running without authentication if the PBM agent connects via a non-localhost interface (such as a container hostname or external IP). Because MongoDB restricts the shutdown command to the localhost interface in non-authenticated environments, PBM will be unable to stop the node to perform the restore. To avoid this limitation, ensure that the PBM_MONGODB_URI uses a localhost connection or enable authentication for your MongoDB deployment. + ## Oplog slicing for point-in-time recovery Oplog slicing is an integral part of the point-in-time recovery routine that enables you to restore from a backup up to a specific moment. Read more about [point-in-time recovery](point-in-time-recovery.md). -**For MongoDB 8.0 and higher versions** +**MongoDB 8.0 and higher versions** If you [unshard a collection :octicons-link-external-16:](https://www.mongodb.com/docs/v8.0/reference/command/unshardCollection/), make a fresh backup and re-enable point-in-time recovery oplog slicing to prevent data inconsistency and restore failure. -**For in MongoDB 5.0 and higher versions** +**MongoDB 5.0 and higher versions** If you [reshard :octicons-link-external-16:](https://www.mongodb.com/docs/manual/core/sharding-reshard-a-collection/) a collection, make a fresh backup and re-enable point-in-time recovery oplog slicing to prevent data inconsistency and restore failure. diff --git a/docs/features/multi-storage.md b/docs/features/multi-storage.md index 29e1b364..71b4c0ff 100644 --- a/docs/features/multi-storage.md +++ b/docs/features/multi-storage.md @@ -163,9 +163,11 @@ Before you start, make sure that `pbm-agents` have the read permissions to backu 2. To make a point-in-time restore, you must explicitly pass the backup name for the `pbm restore` command: ```bash - pbm-restore --time= --base-snapshot + pbm restore --time= --base-snapshot ``` + !!! admonition "Version added: [2.14.0](../release-notes/2.14.0.md)" + Before a restore operation is executed you have to confirm the action (to bypass it, add the `-y` or `--yes` flag). 3. After the restore is complete, do the required post-restore steps depending on the restore type. 4. Make a fresh backup to serve as the new base for future restores. diff --git a/docs/features/physical.md b/docs/features/physical.md index 5eeff7b5..d954b875 100644 --- a/docs/features/physical.md +++ b/docs/features/physical.md @@ -30,7 +30,7 @@ During physical backups and restores, ``pbm-agents`` don't export / import data ## Availability and system requirements -* Percona Server for MongoDB starting from versions 4.2.15-16, 4.4.6-8, 5.0 and higher. +* For current Percona Backup for MongoDB versions, physical backups require Percona Server for MongoDB 7.0 or newer. For support on older Percona Server for MongoDB versions, see the compatibility matrix in [Supported versions](../details/versions.md). * WiredTiger storage engine, since physical backups heavily rely on the WiredTiger [`$backupCursor` :octicons-link-external-16:](https://docs.percona.com/percona-server-for-mongodb/latest/backup-cursor.html) functionality. !!! warning @@ -84,35 +84,22 @@ The physical restore in mixed deployments has no restrictions except the version !!! admonition "Version added: [2.0.0](../release-notes/2.0.0.md)" -You can back up and restore data which is encrypted at rest. Thereby you ensure data safety and can also comply with security requirements such as GDPR, HIPAA, PCI DSS, or PHI. +You can back up and restore data that is encrypted at rest. Thereby, you ensure data security and also comply with security requirements such as GDPR, HIPAA, PCI DSS, and PHI. If you use an external KMS such as HashiCorp Vault, OpenBao, or KMIP, you need the master encryption key identifier to restore the data. For security reasons, the encryption key is not stored or shown as part of the backup. -During a backup, Percona Backup for MongoDB stores the encryption settings in the backup metadata. You can verify them using the [`pbm describe-backup`](../reference/pbm-commands.md#pbm-describe-backup) command. Note that the encryption key is not stored nor shown as part of the backup. +During a backup, Percona Backup for MongoDB stores the encryption settings in the backup metadata. You can verify them using the [`pbm describe-backup`](../reference/pbm-commands.md#pbm-describe-backup) command. -!!! important +!!! admonition "Version added: [2.14.0](../release-notes/2.14.0.md)" + Additionally, PBM stores the encryption key identifier in the backup metadata. You need Percona Server for MongoDB (PSMDB) 7.0.22-12 and 8.0.12-4 or higher to use this feature. If you're using older versions of PSMDB or PBM, you have to store the identifier externally and pass it in the restore configuration. - Make sure that you know which master encryption key was used and keep it safe, as this key is required for the restore. +To restore the encrypted data from the backup, you can just configure the same data-at-rest encryption settings on all nodes of your destination cluster or replica set to match the settings of the original cluster where you made the backup. -!!! note - - Starting with [Percona Server for MongoDB version 4.4.19-19 :octicons-link-external-16:](https://docs.percona.com/percona-server-for-mongodb/4.4/release_notes/4.4.19-19.html), [5.0.15-13 :octicons-link-external-16:](https://docs.percona.com/percona-server-for-mongodb/5.0/release_notes/5.0.15-13.html), [6.0.5-4 :octicons-link-external-16:](https://docs.percona.com/percona-server-for-mongodb/6.0/release_notes/6.0.5-4.html) and higher, the master key rotation for data-at-rest encrypted with HashiCorp Vault has been improved to use the same secret key path on every server in your entire deployment. For the restore with earlier versions of Percona Server for MongoDB and PBM 2.0.5 and earlier, see the [Restore for Percona Server for MongoDB **before** 4.4.19-19, 5.0.15-13, 6.0.5-4 using HashiCorpVault](#restore-for-percona-server-for-mongodb-before-4419-19-5015-13-605-4-using-hashicorpvault) section. - -To restore the encrypted data from the backup, configure the same data-at-rest encryption settings on all nodes of your destination cluster or replica set to match the settings of the original cluster where you made the backup. - -During the restore, Percona Backup for MongoDB restores the data to all nodes using the same master key. We recommend to rotate the master encryption key afterwards for extra security. +During the restore, Percona Backup for MongoDB restores the data to all nodes using the same master key. We recommend rotating the master encryption key afterward for extra security. To learn more about master key rotation, refer to the following documentation: * [Master key rotation in HashiCorp Vault server :octicons-link-external-16:](https://docs.percona.com/percona-server-for-mongodb/6.0/vault.html#key-rotation) * [KMIP master key rotation :octicons-link-external-16:](https://www.mongodb.com/docs/manual/tutorial/rotate-encryption-key/#kmip-master-key-rotation) -### Restore for Percona Server for MongoDB **before** 4.4.19-19, 5.0.15-13, 6.0.5-4 using HashiCorpVault - -In Percona Server for MongoDB version **before** 4.4.19-19, 5.0.15-13, 6.0.5-4 with Vault server used for data-at-rest encryption, the master key rotation with the same key used for 2+ nodes is not supported. If you run these versions of Percona Server for MongoDB and PBM before 2.1.0, consider using the scenario where PBM restores the data on one node of every replica set. The remaining nodes receive the data during the initial sync. - -Configure data-at-rest encryption on one node of every shard in your destination cluster or a replica set. - -During the restore, Percona Backup for MongoDB restores the data on the node where the encryption key matches the one with which the backed up data was encrypted. The other nodes are not restored, so the restore has the "partlyDone" status. You can start this node and initiate the replica set. The remaining nodes receive the data as the result of the initial sync from the restored node. - ## Physical restores with a fallback directory !!! admonition "Version added: [2.10.0](../release-notes/2.10.0.md)" @@ -191,7 +178,10 @@ A restore can succeed on most nodes, but it might fail on a few, resulting in a ```bash pbm restore --time