diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index e4af0a33..1fc7df99 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -1,18 +1,25 @@ -name: Check docs with Vale -on: - pull_request: - branches: - - main - +name: Percona Backup for MongoDB 2.15.0 docs +on: + push: + branches: + - 2.15.0 jobs: - vale: - name: runner / vale + build: + name: Deploy docs runs-on: ubuntu-latest - steps: - - name: Checkout + + steps: + #Pull the latest changes + - name: Chekout code uses: actions/checkout@v3 with: fetch-depth: 0 + #Prepare the env + - name: Set up Python + uses: actions/setup-python@v3 + with: + python-version: '3.x' + #Configure git - name: Configure git env: @@ -23,16 +30,33 @@ jobs: git config user.email "github-action@users.noreply.github.com" git config user.password "${ROBOT_TOKEN}" echo "GIT_USER=percona-platform-robot:${ROBOT_TOKEN}" >> $GITHUB_ENV - - #Run check - - name: reviewdog - uses: errata-ai/vale-action@reviewdog - with: - vale_flags: "--glob=*.md" -# fail_on_error: true - reporter: github-check - env: - # Required, set by GitHub actions automatically: - # https://docs.github.com/en/actions/security-guides/automatic-token-authentication#about-the-github_token-secret - GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}} - + #Set up MkDocs + - name: Install MkDocs + run: | + python -m pip install --upgrade pip + pip install wheel + if [ -f requirements.txt ]; then pip install -r requirements.txt; fi + #Set up PlantUML + - name: Setup PlantUML dependencies + run: | + sudo apt install -y graphviz + + # Deploy docs + - name: Deploy docs + run: | + mike deploy 2.15.0 -b publish -p + mike retitle 2.15.0 "2.15.0" -b publish -p + mike set-default 2.15.0 -b publish -p +# - name: Install Node.js 14.x +# uses: percona-platform/setup-node@v2 +# with: +# node-version: "14" +# +# - name: Spelling +# run: | +# npx markdown-spellcheck --report --en-us --ignore-acronyms --ignore-numbers "docs/**/*.md" || true + # Ignore errors, just inspect results +# - name: Grammar +# run: | +# npx write-good --no-passive docs/**/*.md || true +# # Ignore errors, just inspect results diff --git a/.gitignore b/.gitignore index 4da6fc20..6260d046 100644 --- a/.gitignore +++ b/.gitignore @@ -9,9 +9,13 @@ venv/ # Local Netlify folder .netlify site +.cache/ styles/ # Allow !styles/config/vocabularies/Percona/** + +# Generated plugin cache +.cache/plugin/git-committers/ diff --git a/_resourcepdf/overrides/main.html b/_resourcepdf/overrides/main.html index 388f22f5..6c500224 100644 --- a/_resourcepdf/overrides/main.html +++ b/_resourcepdf/overrides/main.html @@ -44,8 +44,8 @@ {% endif %} - - + + {% endblock %} {% block site_nav %} diff --git a/_resourcepdf/overrides/partials/banner.html b/_resourcepdf/overrides/partials/banner.html index d1bcc0a5..1d71167b 100644 --- a/_resourcepdf/overrides/partials/banner.html +++ b/_resourcepdf/overrides/partials/banner.html @@ -4,6 +4,6 @@
-Get help from Percona +Get help from Percona
diff --git a/_resourcepdf/overrides/partials/edit.html b/_resourcepdf/overrides/partials/edit.html index c9a11ebb..dc3bbae9 100644 --- a/_resourcepdf/overrides/partials/edit.html +++ b/_resourcepdf/overrides/partials/edit.html @@ -13,7 +13,7 @@ - Percona logo

-

Backup for MongoDB 2.14.0

+

Backup for MongoDB 2.15.0

{% if config.site_description %}

{{ config.site_description }}

{% endif %} -

2.14.0 (April 29, 2026)

\ No newline at end of file +

2.15.0 (June 17, 2026)

\ No newline at end of file diff --git a/docs/details/oci-storage.md b/docs/details/oci-storage.md new file mode 100644 index 00000000..44ff3156 --- /dev/null +++ b/docs/details/oci-storage.md @@ -0,0 +1,424 @@ +# Oracle Cloud Infrastructure Object Storage + +Percona Backup for MongoDB (PBM) supports [OCI Object Storage](https://docs.oracle.com/en-us/iaas/Content/Object/Concepts/objectstorageoverview.htm) +as a remote backup destination through a dedicated OCI native +driver. PBM connects to OCI Object Storage using one of the following authentication types: + +| **Authentication type** | **Use when** | +| --- | --- | +| `userPrincipal` | PBM runs anywhere; authenticates with OCI API signing keys | +| `instancePrincipal` | PBM runs on an OCI Compute instance | +| `okeWorkloadIdentity` | PBM runs inside an OKE enhanced cluster | + +For information on workload identity based authentication methods, refer to the sections on [Instance Principal](oci-wif.md#instanceprincipal) and [OKE Workload Identity](oci-wif.md#okeworkloadidentity). + + +## Prerequisites + +Before configuring PBM, ensure that you have: + +- An active OCI tenancy with at least one subscribed region +- The OCI CLI installed and configured (oci setup config) if you intend to use command-line tools. You can also complete the configuration using the OCI Console. + See the [OCI CLI documentation](https://docs.oracle.com/en-us/iaas/Content/API/SDKDocs/cliinstall.htm) + for installation instructions +- An OCI user with permission to create compartments, buckets, dynamic groups, and IAM policies in your tenancy + +Initialize the OCI CLI configuration if you have not done so already: + +```sh +oci setup config +``` + +Use your tenancy home region as the default CLI region. If the setup generated a new API key, upload the public key +to your OCI user: + +```sh +cat ~/.oci/oci_api_key_public.pem +``` + +In the OCI Console, go to **User settings → Tokens and keys → +API keys → Add API key**, paste the public key, and confirm +the fingerprint matches `~/.oci/config`. + +If needed, update local file permissions: + +```bash +oci setup repair-file-permissions --file ~/.oci/config +oci setup repair-file-permissions --file ~/.oci/oci_api_key.pem +``` + +## Verify region access + +Check the regions available to your tenancy: + +```bash +oci iam region-subscription list \ + --region \ + --output table +``` + +!!! note + The region specified in the configuration must be enabled and subscribed to in your OCI tenancy. + +## Set up OCI resources + +### Export variables + +Set the following variables before running any commands in this +section. All subsequent commands reference them. + +```sh +export HOME_REGION= # e.g. us-ashburn-1 +export BUCKET_REGION= # e.g. eu-frankfurt-1 +export COMPARTMENT_NAME= +export BUCKET_NAME= +``` +Retrieve and export the values PBM requires: + +```sh +export TENANCY_OCID=$( + oci iam tenancy get \ + --tenancy-id "$(awk -F= '/^tenancy=/{print $2}' ~/.oci/config)" \ + --region "$HOME_REGION" \ + --query 'data.id' \ + --raw-output +) + +export USER_OCID=$(awk -F= '/^user=/{print $2}' ~/.oci/config) +export FINGERPRINT=$(awk -F= '/^fingerprint=/{print $2}' ~/.oci/config) +export KEY_FILE=$(awk -F= '/^key_file=/{print $2}' ~/.oci/config) +export KEY_FILE="${KEY_FILE/#\~/$HOME}" +export NAMESPACE=$( + oci os ns get \ + --region "$BUCKET_REGION" \ + --query 'data' \ + --raw-output +) + +echo "TENANCY_OCID: $TENANCY_OCID" +echo "USER_OCID: $USER_OCID" +echo "FINGERPRINT: $FINGERPRINT" +echo "KEY_FILE: $KEY_FILE" +echo "NAMESPACE: $NAMESPACE" +``` +Verify all five values are populated before continuing. An empty value means the OCI CLI is not authenticated or the variable was not set correctly. + +### Create a compartment + +!!! tip "Important" + While OCI resources always require a compartment, creating a dedicated one for PBM backup resources is optional. You can use the root compartment. However, Percona recommends using a separate compartment for PBM resources to improve organization and simplify IAM policy management. + +Create a compartment for PBM backup resources: + +```sh +oci iam compartment create \ + --region "$HOME_REGION" \ + --compartment-id "$TENANCY_OCID" \ + --name "$COMPARTMENT_NAME" \ + --description "PBM OCI Object Storage backup" +``` +Wait until the compartment is active, then export its OCID: + +```sh +export COMPARTMENT_OCID=$( + oci iam compartment list \ + --region "$HOME_REGION" \ + --compartment-id "$TENANCY_OCID" \ + --compartment-id-in-subtree true \ + --all \ + --query "data[?name=='$COMPARTMENT_NAME' && \"lifecycle-state\"=='ACTIVE'].id | [0]" \ + --raw-output +) + +echo "COMPARTMENT_OCID: $COMPARTMENT_OCID" +``` +### Create an Object Storage bucket + +Create the bucket: + +```sh +oci os bucket create \ + --region "$BUCKET_REGION" \ + --namespace-name "$NAMESPACE" \ + --compartment-id "$COMPARTMENT_OCID" \ + --name "$BUCKET_NAME" +``` + +Verify the bucket was created: + +```sh +oci os bucket get \ + --region "$BUCKET_REGION" \ + --namespace-name "$NAMESPACE" \ + --bucket-name "$BUCKET_NAME" \ + --query 'data.{name:name,namespace:namespace}' \ + --output table +``` + +### Create IAM policies + +PBM must be able to create, read, overwrite, and delete backup objects. + +Ensure your OCI user (or the group it belongs to) has permissions to manage objects in the target bucket/compartment. + +Additionally, PBM requires a native copy policy that grants the OCI Object Storage service permission to copy objects internally (for server-side copy operations): + +```sh +oci iam policy create \ + --region "$HOME_REGION" \ + --compartment-id "$TENANCY_OCID" \ + --name "pbm-native-copy-$BUCKET_REGION" \ + --description "Allow Object Storage service to copy PBM objects" \ + --statements "[\"Allow service objectstorage-$BUCKET_REGION to manage object-family \ + in compartment $COMPARTMENT_NAME where any { \ + request.permission='OBJECT_READ', \ + request.permission='OBJECT_INSPECT', \ + request.permission='OBJECT_CREATE', \ + request.permission='OBJECT_OVERWRITE', \ + request.permission='OBJECT_DELETE'}\"]" +``` + +!!! note + IAM policy changes can take up to 2 minutes to propagate. If PBM reports an authorization error immediately after creating the policies, wait 2 minutes and retry. + +## Configure PBM + +### userPrincipal + +Use this when PBM runs outside OCI, or when you want to +authenticate with OCI API signing keys. + +Generate the correctly indented private key before creating +the config file: + +```sh +sed 's/^/ /' "$KEY_FILE" +``` +Create the configuration file: + +```yaml +storage: + type: oci + oci: + region: + namespace: + bucket: + prefix: pbm + credentials: + type: userPrincipal + userPrincipal: + tenancy: + user: + fingerprint: + privateKey: | + -----BEGIN PRIVATE KEY----- + ... + -----END PRIVATE KEY----- +``` +!!! warning + The `user` value must be a user OCID starting with + `ocid1.user.oc1`. A bucket or compartment OCID causes + a 401 authentication failure. + +!!! tip + Indent the private key correctly before adding it to the configuration: + + ```sh + sed 's/^/ /' "$KEY_FILE" + ``` + +## Apply the PBM configuration + +Apply the configuration: + +```bash +pbm config --file /path/to/oci-config.yaml +``` + +Force PBM to resync the storage configuration: + +```sh +pbm config --force-resync +``` + +## Verify the configuration + +Verify all agents connected and storage initialized successfully: + +```sh +pbm status +``` + +??? example "Output" + + ```sh + $ pbm status + Cluster: + ======== + rs1: + - rs101:27017 [S]: pbm-agent [v2.15.0] OK + - rs102:27017 [S]: pbm-agent [v2.15.0] OK + - rs103:27017 [P]: pbm-agent [v2.15.0] OK + + PITR incremental backup: + ======================== + Status [OFF] + + Currently running: + ================== + (none) + + Backups: + ======== + Main storage: + Type: OCI + Region: us-ashburn-1 + Path: oci:////pbm + (no snapshots or PITR chunks) + ``` + +Every node must show `pbm-agent` as `OK` and storage as `ok`. + +Run a test backup to confirm end-to-end functionality: + +```sh +pbm backup +pbm list +``` + +??? example "Output" + + ```sh + $ pbm backup + Starting backup "2026-06-12T07:11:31Z"..... + Backup "2026-06-12T07:11:31Z" saved to remote store (path: "oci:////pbm") + ``` + + ```sh + $ pbm list + Backup snapshots: + NAME TYPE PROFILE SELECTIVE BASE RESTORE TIME + ----------------------------------------------------- + 2026-06-11T13:14:51Z logical no no 2026-06-11T13:15:07 + 2026-06-12T07:04:27Z logical no no 2026-06-12T07:04:42 + 2026-06-12T07:11:31Z logical no no 2026-06-12T07:11:46 + + PITR : + ``` + +## Server-side encryption + +PBM supports OCI Object Storage server-side encryption using either OCI Key Management Service (KMS) keys or customer-provided encryption keys (SSE-C). These methods are mutually exclusive. Configure only one encryption mode at a time. + +OCI Object Storage always encrypts data at rest using server-side encryption (SSE). By default, OCI uses Oracle-managed encryption keys and encryption cannot be disabled. The encryption settings described in this section are intended for environments that require greater control over key management, such as using customer-managed keys in OCI Key Management Service (KMS) or customer-provided encryption keys (SSE-C). + +### SSE with OCI KMS + +Use OCI KMS encryption when you want OCI to manage encryption and key lifecycle through OCI Vault and Key Management. + +#### Create a KMS key + +In the OCI Console, navigate to: + +**Identity & Security → Key Management & Secret Management → Vault** + +Open an existing vault or create a new vault in `$BUCKET_REGION`, then select: + +**Master Encryption Keys → Create Key** + +Configure the key with the following settings: + +- Algorithm: AES +- Key length: 256 bits + +Copy the generated key OCID. + +Export the key OCID and OCI IAM group name: + +```sh +export KMS_KEY_OCID="" +export OCI_GROUP_NAME="Administrators" +export KMS_POLICY_NAME="pbm-oci-kms-$BUCKET_REGION" +``` + +If your tenancy uses identity domains, specify the group name in identity-domain-qualified format: + +```sh +export OCI_GROUP_NAME="'Default'/''" +``` + +#### Create IAM policies for KMS access + +Create a policy that allows both the PBM user group and the regional Object Storage service to use the KMS key. + +The object access statement is only required if the OCI group does not already have Object Storage permissions in the target compartment. + +```sh +export KMS_OBJECT_POLICY_STATEMENT="Allow group $OCI_GROUP_NAME to manage object-family in compartment $COMPARTMENT_NAME" +export KMS_USER_POLICY_STATEMENT="Allow group $OCI_GROUP_NAME to use keys in compartment $COMPARTMENT_NAME" +export KMS_OBJECTSTORAGE_POLICY_STATEMENT="Allow service objectstorage-$BUCKET_REGION to use keys in compartment $COMPARTMENT_NAME" + +oci iam policy create \ + --region "$HOME_REGION" \ + --compartment-id "$TENANCY_OCID" \ + --name "$KMS_POLICY_NAME" \ + --description "Allow PBM user principal and Object Storage to use KMS keys in $BUCKET_REGION" \ + --statements "[\"$KMS_OBJECT_POLICY_STATEMENT\",\"$KMS_USER_POLICY_STATEMENT\",\"$KMS_OBJECTSTORAGE_POLICY_STATEMENT\"]" +``` + +!!! note + Wait 1–2 minutes for OCI IAM policy propagation before applying the PBM configuration. + + Without the Object Storage service policy, PBM uploads fail with `NotAuthorizedOrFoundKmsKey` during `CreateMultipartUpload` operations. + +#### Configure PBM + +Add the following to the OCI storage configuration: + +```yaml +serverSideEncryption: + kmsKeyID: +``` + +!!! warning + Do not configure `sseCustomerKey` together with `kmsKeyID`. PBM treats OCI KMS encryption and SSE-C as mutually exclusive options. + +### SSE-C (Customer-Provided Encryption Keys) + +Use SSE-C when you want full control of the encryption key material used to encrypt backup objects. PBM sends the encryption key with every Object Storage request. OCI uses the supplied key to encrypt and decrypt objects but does not persist the key. + +#### Generate an SSE-C key + +Generate a 256-bit AES key and encode it in Base64: + +```sh +openssl rand 32 | base64 +``` + +Store the generated value securely. PBM requires the same key for all future backup, restore, and object access operations. + +#### Configure PBM + +Add the customer-provided key to the storage configuration: + +```yaml +serverSideEncryption: + sseCustomerKey: +``` + +#### Verify encryption + +After a successful backup, verify that uploaded objects are encrypted with SSE-C: + +```sh +oci os object head \ + --region "$BUCKET_REGION" \ + --namespace-name "$NAMESPACE" \ + --bucket-name "$BUCKET_NAME" \ + --name "" +``` + +The response indicates that the object uses customer-supplied encryption keys. + +!!! warning + OCI does not retain SSE-C keys. If the key is lost, encrypted backup objects cannot be decrypted or restored. \ No newline at end of file diff --git a/docs/details/oci-wif.md b/docs/details/oci-wif.md new file mode 100644 index 00000000..b58d8b1e --- /dev/null +++ b/docs/details/oci-wif.md @@ -0,0 +1,111 @@ +# Oracle Cloud Infrastructure (OCI) Object Storage with Workload Identity Authentication + +Percona Backup for MongoDB (PBM) supports multiple authentication methods for Oracle Cloud Infrastructure (OCI) Object Storage, including Workload Identity. With Workload Identity, PBM can access OCI resources without storing or managing API keys, reducing operational overhead and improving security. + +Percona Backup for MongoDB (PBM) supports the following keyless (identity-based) authentication options: + +| Auth type | When to use | +|---|---| +| `instancePrincipal`| PBM is running on a virtual machine inside OCI | +| `okeWorkloadIdentity`| PBM is running inside an OKE enhanced cluster| + +## instancePrincipal + +Choose `instancePrincipal` when PBM runs directly on an OCI Compute instance. PBM automatically obtains OCI credentials from the instance, eliminating the need for credential files or API keys. + +### Before you begin + +You need: + +- The [Oracle Cloud Identifier (OCID) :octicons-link-external-16:](https://docs.oracle.com/en-us/iaas/Content/General/Concepts/identifiers.htm#Oracle){:target="_blank"} of the OCI Compute instance running PBM +- The name of the OCI bucket PBM will use for backups. + +### Procedure + +Follow these steps to set up OCI using **`instancePrincipal`:** + +1. **Create a dynamic group for the instance** + + OCI IAM policies cannot target individual instances directly. You must first add the instance to a dynamic group, then write a policy against that group. + + ```sh + oci iam dynamic-group create \ + --region "$HOME_REGION" \ + --compartment-id "$TENANCY_OCID" \ + --name "$INSTANCE_DYNAMIC_GROUP_NAME" \ + --description "PBM VM instance principal" \ + --matching-rule "ANY {instance.id = '$INSTANCE_OCID'}" + ``` + + Replace the following variables: + + | Variable | Description | + |---|---| + | `HOME_REGION` | Your tenancy's home region (e.g. `us-ashburn-1`) | + | `TENANCY_OCID` | OCID of your OCI tenancy | + | `INSTANCE_DYNAMIC_GROUP_NAME` | A name for the dynamic group (e.g. `pbm-vm-group`) | + | `INSTANCE_OCID` | OCID of the Compute instance running PBM | + +2. **Create an IAM policy** + + Grant the dynamic group permission to manage objects in the target bucket: + + ```sh + export INSTANCE_POLICY_STATEMENT="Allow dynamic-group $INSTANCE_DYNAMIC_GROUP_NAME \ + to manage objects in compartment $COMPARTMENT_NAME \ + where target.bucket.name = '$BUCKET_NAME'" + + oci iam policy create \ + --region "$HOME_REGION" \ + --compartment-id "$TENANCY_OCID" \ + --name "$INSTANCE_POLICY_NAME" \ + --description "Allow PBM VM instance principal to access $BUCKET_NAME" \ + --statements "[\"$INSTANCE_POLICY_STATEMENT\"]" + ``` + + Replace the following additional variables: + + | Variable | Description | + |---|---| + | `COMPARTMENT_NAME` | Name of the compartment containing the bucket | + | `BUCKET_NAME` | Name of the OCI Object Storage bucket | + | `INSTANCE_POLICY_NAME` | A name for the policy (e.g. `pbm-vm-policy`) | + +3. **Configure PBM authentication** + + In your PBM configuration, set the storage type to `oci` and the credentials type to `instancePrincipal`. No key file or passphrase is needed. + + ```yaml + storage: + type: oci + oci: + region: + namespace: + bucket: + prefix: + credentials: + type: instancePrincipal + ``` + +## okeWorkloadIdentity + +Choose `okeWorkloadIdentity` when PBM runs as a workload in an Oracle Kubernetes Engine (OKE) enhanced cluster. The Kubernetes service account token is exchanged for OCI credentials automatically by the OKE Workload Identity service. + +!!! note + Your OKE cluster must be an **enhanced cluster** with Workload Identity enabled. Basic clusters do not support this feature. + +In your PBM configuration, set the storage type to `oci` and the credentials type to `okeWorkloadIdentity`: + +```yaml +storage: + type: oci + oci: + region: + namespace: + bucket: + prefix: + credentials: + type: okeWorkloadIdentity +``` + +For setup instructions, see [Configure OKE Workload Identity for workloads :octicons-link-external-16:](https://docs.oracle.com/en-us/iaas/Content/ContEng/Tasks/contenggrantingworkloadaccesstoresources.htm){:target="_blank"}. \ No newline at end of file diff --git a/docs/details/pbm-user-roles.md b/docs/details/pbm-user-roles.md new file mode 100644 index 00000000..d3729148 --- /dev/null +++ b/docs/details/pbm-user-roles.md @@ -0,0 +1,49 @@ +# PBM user database roles + +Percona Backup for MongoDB requires a dedicated database user holding a specific set of MongoDB roles. The table below gives a quick overview; the sections that follow explain why each role is needed and what it does — and does not — grant. + +| Role | Scope | Access type | Purpose | +|-----------------|------------------|--------------|-----------------------------------------------| +| `readWrite` | `admin` db only | Read + write | PBM metadata / agent coordination collections | +| `backup` | All databases | Read-only | Full data + oplog snapshot for backup | +| `clusterMonitor`| Cluster metadata | Read-only | Topology awareness, safe scheduling | +| `restore` | All databases | Write | Replay data during restore operations | +| `pbmAnyAction` | All resources | Any action | Privileged commands not covered by built-in roles (`applyOps`, `_configsvrBalancerStop`, `_configsvrBalancerStatus`, `shutdown`) | + +## Built-in MongoDB roles + +### `readWrite` (on `admin` db) + +PBM stores its operational metadata — backup status, restore progress, configuration, and agent coordination — in the PBM control collections in the `admin` database (for example, `admin.pbmConfig`, `admin.pbmBackups`, `admin.pbmAgents`, and others; see [PBM control collections](../details/control-collections.md)). The `readWrite` role grants PBM the ability to read from and write to these collections so all agents in a cluster can share state and coordinate operations. +This role is scoped to the `admin` database only. It does not grant read or write access to application databases. + +### `backup` + +The `backup` role is a MongoDB built-in role that allows reading all data across all databases and collections (via `listDatabases`, `listCollections`, and `find` on all namespaces), as well as reading the oplog (`local.oplog.rs`). PBM requires this to stream a consistent snapshot of all data during a backup, including the oplog data needed for point-in-time recovery (PITR). + +This is a read-only role with respect to application data. No write access to application databases is granted by this role alone. + +### `clusterMonitor` + +PBM agents need to query the cluster topology and health — member states, replication lag, shard configuration, and whether a node is primary or secondary — to make safe decisions about where to run a backup, when to wait for replication to catch up, and how to coordinate across a replica set or sharded cluster. The `clusterMonitor` role grants access to commands like `serverStatus`, `replSetGetStatus`, `listShards`, and similar diagnostic commands. + +This role grants read-only access to monitoring and operational metadata. It does not allow modifying cluster configuration or accessing application data. + +### `restore` + +During a restore operation, PBM needs to write data back into all databases and collections, recreate indexes, and replay oplog entries to reach a consistent point-in-time state. The `restore` role grants the necessary `insert`, `update`, and `createCollection`/`createIndex` privileges across all namespaces to perform these operations. + +This role is only exercised during a restore operation. It grants broad write privileges and should be treated as a sensitive, privileged role in your access review process. + +## Custom role + +### `pbmAnyAction` (custom role on `admin` db) + +This custom role grants the `anyAction` privilege on `anyResource`, which is effectively full administrative access. PBM uses this capability for a limited set of commands that fall outside what the standard built-in roles cover: +- `setParameter` / `getParameter` — to read or temporarily adjust certain `mongod` parameters during backup/restore (for example, disabling the balancer on sharded clusters). +- `fsync` / `fsyncUnlock` — on some backup paths (particularly for physical/hot backups with Percona Server for MongoDB), PBM may need to flush and lock the WiredTiger storage engine. +- Oplog-related and internal commands — certain replication and storage-engine commands needed for consistent point-in-time backups are not exposed by any standard role. + +!!! note "Compliance note" + + This is the most privileged role in the set. It is intentionally custom and narrowly justified by gaps in MongoDB's built-in role model. This role is assigned to a dedicated service account (`pbmuser`) used exclusively by the PBM agent process — not by any human operator or application. diff --git a/docs/details/storage-configuration.md b/docs/details/storage-configuration.md index 5f49941f..d06bedab 100644 --- a/docs/details/storage-configuration.md +++ b/docs/details/storage-configuration.md @@ -17,6 +17,7 @@ Percona Backup for MongoDB supports the following storage types: * [MinIO and S3-compatible storage](minio.md) * [Filesystem server storage](filesystem-storage.md) * [Microsoft Azure Blob storage](azure.md) +* [Oracle Cloud Infrastructure Object Storage](oci-storage.md) * [Alibaba Cloud OSS storage](oss.md) ### Considerations for choosing a backup storage type for s3-compatible storages diff --git a/docs/install/configure-authentication.md b/docs/install/configure-authentication.md index ef895329..519a9c04 100644 --- a/docs/install/configure-authentication.md +++ b/docs/install/configure-authentication.md @@ -6,7 +6,7 @@ Percona Backup for MongoDB uses the authentication and authorization subsystem o * [Set a valid MongoDB connection URI string for **pbm-agent**](#set-the-mongodb-connection-uri-for-pbm-agent) * [Set a valid MongoDB connection URI string for `pbm` CLI](#set-the-mongodb-connection-uri-for-pbm-cli) -## Create the `pbm` user +## Create a `pbm` user !!! info @@ -45,6 +45,8 @@ Percona Backup for MongoDB uses the authentication and authorization subsystem o You can change the `username` and `password` values and specify other options for the `createUser` command as you require. But you must grant this user the roles as shown above. +For an explanation of why each role is required and what it does and does not grant, see [PBM user roles reference](../details/pbm-user-roles.md). + !!! tip diff --git a/docs/install/docker.md b/docs/install/docker.md index 49971f1d..fd607783 100644 --- a/docs/install/docker.md +++ b/docs/install/docker.md @@ -32,7 +32,6 @@ By default, Docker will pull the image from Docker Hub if it is not available lo Start Percona Backup for MongoDB container with the following command: - ```bash docker run --name -e PBM_MONGODB_URI="mongodb://:@:" -d percona/percona-backup-mongodb: ``` @@ -94,7 +93,7 @@ docker exec -it pbm backup where `` is the name you assigned to the container and `pbm backup` is the command to start a backup. -In the same way you can run other pbm commands. Find the full list of available commands in [Percona Backup for MongoDB reference](https://docs.percona.com/percona-backup-mongodb/reference/pbm-commands.html). +In the same way you can run other pbm commands. Find the full list of available commands in [Percona Backup for MongoDB reference](https://docs.percona.com/percona-backup-mongodb/2.15.0/reference/pbm-commands.html). ## Next steps diff --git a/docs/reference/backup-options.md b/docs/reference/backup-options.md index 5f5c052e..c05696a3 100644 --- a/docs/reference/backup-options.md +++ b/docs/reference/backup-options.md @@ -13,6 +13,7 @@ backup: startingStatus: 60 oplogSpanMin: numParallelCollections: + numParallelFiles: ``` ## priority @@ -121,3 +122,14 @@ The duration (in minutes) of oplog slices saved with the logical backup snapshot The number of parallel collections to process during a logical backup. By default, the number of parallel collections is half of the number of CPU cores. By setting the value for this option you define the new default. Available starting with version 2.7.0. + +## backup.numParallelFiles + +*Type*: int
+*Default*: 1
+*Storage*: Filesystem / NFS only
+*Backup type:* Physical only + +The number of files to copy in parallel during a physical backup to filesystem or NFS storage. + +The default value is `1`, which copies files sequentially. diff --git a/docs/reference/configuration-options.md b/docs/reference/configuration-options.md index 7a18330c..9cbff874 100644 --- a/docs/reference/configuration-options.md +++ b/docs/reference/configuration-options.md @@ -7,7 +7,7 @@ *Type*: string
*Required*: YES -Remote backup storage type. Supported values: `s3`, `minio`, `gcs`, `filesystem`, `azure`. +Remote backup storage type. Supported values: `s3`, `minio`, `gcs`, `filesystem`, `azure`, `oci`, `oss`. ## AWS S3 storage options @@ -679,6 +679,106 @@ The minimum time to wait before the next retry, specified as a `time.Duration`. The maximum time to wait before the next retry, specified as a `time.Duration`. Units like ms, s, etc., are supported. Defaults to nanoseconds if no unit is provided. +## OCI Object Storage options + +```yaml +storage: + type: oci + oci: + region: + namespace: + bucket: + prefix: + credentials: + type: userPrincipal + userPrincipal: + tenancy: + user: + fingerprint: + privateKey: | + -----BEGIN PRIVATE KEY----- + ... + -----END PRIVATE KEY----- +``` + +### storage.oci.region + +*Type*: string
+*Required*: YES + +The OCI region where your Object Storage bucket is located. + +### storage.oci.namespace + +*Type*: string
+*Required*: YES + +The Object Storage namespace for your OCI tenancy. + +### storage.oci.bucket + +*Type*: string
+*Required*: YES + +The name of the Object Storage bucket where PBM stores backups. + +### storage.oci.prefix + +*Type*: string
+*Required*: NO + +The path prefix in the bucket. If undefined, backups are stored in the bucket root. + +### storage.oci.credentials.type + +*Type*: string
+*Required*: NO
+*Default*: `userPrincipal` + +Authentication type for OCI access. Supported values: `userPrincipal`, `instancePrincipal`, `okeWorkloadIdentity`. + +### storage.oci.credentials.userPrincipal.tenancy + +*Type*: string
+*Required*: YES (when `storage.oci.credentials.type=userPrincipal`) + +The tenancy OCID for OCI API signing key authentication. + +### storage.oci.credentials.userPrincipal.user + +*Type*: string
+*Required*: YES (when `storage.oci.credentials.type=userPrincipal`) + +The user OCID for OCI API signing key authentication. + +### storage.oci.credentials.userPrincipal.fingerprint + +*Type*: string
+*Required*: YES (when `storage.oci.credentials.type=userPrincipal`) + +The fingerprint of the uploaded OCI API signing public key. + +### storage.oci.credentials.userPrincipal.privateKey + +*Type*: string
+*Required*: YES (when `storage.oci.credentials.type=userPrincipal`) + +The private key in PEM format that pairs with the uploaded OCI API signing public key. + +### storage.oci.serverSideEncryption.kmsKeyID + +*Type*: string
+*Required*: NO + +OCI KMS key OCID to enable server-side encryption with OCI KMS. + +### storage.oci.serverSideEncryption.sseCustomerKey + +*Type*: string
+*Required*: NO + +Base64-encoded 256-bit key for SSE-C encryption. Do not set this together with `storage.oci.serverSideEncryption.kmsKeyID`. + ## Alibaba Cloud OSS storage options ```yaml diff --git a/docs/reference/pbm-commands.md b/docs/reference/pbm-commands.md index f1c54b23..af5a013c 100644 --- a/docs/reference/pbm-commands.md +++ b/docs/reference/pbm-commands.md @@ -25,6 +25,7 @@ The command accepts the following flags: | `--compression`| Create a backup with compression.
Supported compression methods: `gzip`, `snappy`, `lz4`, `s2`, `pgzip`, `zstd`. Default: `s2`
The `none` value means no compression is done during backup. | | `--compression-level` | Configure the compression level from 0 to 10. The default value depends on the compression method used. | | `--num-parallel-collections`| Sets the number of collections to process in parallel during a specific logical backup. When undefined, `pbm-agent` processes the number of parallel collections defined for the `backup.numParallelCollections` configuration parameter. If that is undefined, the default number of collections to process in parallel is the half of the number of logical CPUs. Available starting with version 2.7.0.| +| `--num-parallel-files`| Sets the number of files to process in parallel during a specific physical backup. When undefined, `pbm-agent` uses the value defined for the `backup.numParallelFiles` configuration parameter. If that is undefined, the default number of files to process in parallel is `1`. | | `-o`, `--out=text` | Shows the output format as either plain text or a JSON object. Supported values: `text`, `json` | | `--wait` | Wait for the backup to finish. The flag blocks the shell session.| | `--wait-time` | The time to wait for PBM to report the status of the command execution. Use this flag together with the `--wait` flag. You can specify the duration in minutes or hours (for example 5m, 1h).

When not set, PBM waits till the command executes.

If it takes longer than the defined waiting time to execute the command, PBM prints the `Operation is in progress. Check pbm status and logs` error message and unblocks the shell session. The `pbm-agent` continues to execute the command enabling you to track its progress via the `pbm status` command. Available starting with version 2.6.0.| @@ -940,6 +941,7 @@ The command accepts the following flags: | `--with-users-and-roles` | Restores users and roles created in custom databases during selective restore. Use this flag with the `--ns` flag. Available starting with version 2.5.0.| | `-c`, `--config` | The path to the `mongod.conf` file | | `--num-parallel-collections`| Sets the number of collections to process in parallel during a specific logical restore. When undefined, `pbm-agent` processes the number of parallel collections defined for the `restore.numParallelCollections` configuration parameter. If that is undefined, the default number of collections is the half of the number of logical CPUs. Available starting with version 2.7.0.| +| `--num-parallel-files` | Sets the number of files to copy in parallel during a specific physical restore from filesystem or NFS storage. When undefined, PBM uses the value configured for the `restore.numParallelFiles` option (default: `1`). | | `--num-insertion-workers-per-collection`| Specifies the number of insertion workers to run concurrently per collection. Increasing the number for large import may increase the speed of the import. Available starting with version 2.8.0.| | `--ns-from`="database.collection" |Specifies the name of the collection you want to restore under a new name. It indicates the collection present in the backup that you are targeting for restoration. Available starting with version 2.8.0.| | `--ns-to`="database.collection" | Specifies the new name for the collection you are restoring from the original one. Available starting with version 2.8.0.| @@ -1119,8 +1121,6 @@ The command accepts the following flags: } ``` - - ## pbm version Shows the version of Percona Backup for MongoDB. diff --git a/docs/reference/restore-options.md b/docs/reference/restore-options.md index 6747acbe..378d3bb4 100644 --- a/docs/reference/restore-options.md +++ b/docs/reference/restore-options.md @@ -6,6 +6,7 @@ restore: numInsertionWorkers: numParallelCollections: numDownloadWorkers: + numParallelFiles: maxDownloadBufferMb: downloadChunkMb: mongodLocation: @@ -99,4 +100,88 @@ 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 +- Fail fast if the balancer cannot be stopped + +### restore.numParallelFiles + +*Type*: int
+*Default*: 0 +*Storage*: Filesystem / NFS only
+*Restore type:* Physical only + +The number of files to copy in parallel during a physical restore from filesystem or NFS storage. + +The default value is `0`, which performs a sequential restore. This is equivalent to setting the value to `1`. + +### restore.indexCommitQuorum + +*Type*: string or int
+*Default*: `votingMembers` + +Specifies how many data-bearing voting nodes must complete an index build before the primary node commits the index during a **logical restore** operation. + +By default, Percona Backup for MongoDB waits for all voting members (`votingMembers`) to complete index building. In large replica sets, this can introduce significant delays if some nodes build indexes slower than others, blocking the entire restore process. + +Following MongoDB index build commit quorum semantics, you can optimize restore performance by setting this option to a lower quorum threshold. + +The following values are supported: + +`votingMembers` (Default): The primary waits for all data-bearing voting members to complete the index build. + +`majority`: The primary commits the index as soon as a simple majority of data-bearing voting members have completed the build. This is recommended for large replica sets to prevent lagging nodes from delaying the restore process. + +``: A specific number of data-bearing voting members (e.g., 3) that must complete the index build. The integer value must be between 1 and the number of data-bearing voting members. A value of 1 means the primary commits immediately after it finishes. + +```sh +pbm config --set restore.indexCommitQuorum=majority +``` + +??? example "Example" + + 1. Run the following command: + + ```sh + pbm config --set restore.indexCommitQuorum=majority + ``` + + 2. Confirm the value was set: + + ```sh + pbm config restore.indexCommitQuorum= + majority + [restore.indexCommitQuorum=majority] + ``` + + 3. Confirm `indexCommitQuorum` appears in the PBM config with the following command: + + ```text + $ pbm config + storage: + type: s3 + s3: + region: us-east-1 + endpointUrl: http://minio:9000 + forcePathStyle: true + bucket: bcp + prefix: pbme2etest + credentials: + access-key-id: '***' + secret-access-key: '***' + maxUploadParts: 10000 + storageClass: STANDARD + insecureSkipTLSVerify: false + pitr: + enabled: false + compression: s2 + backup: + oplogSpanMin: 0 + compression: s2 + restore: + indexCommitQuorum: majority + ``` + + 4. Start the restore and wait for it to complete: + + ```sh + pbm restore -w 2026-05-12T13:28:07Z + ``` diff --git a/docs/reference/sboms-pbm.md b/docs/reference/sboms-pbm.md new file mode 100644 index 00000000..551230e6 --- /dev/null +++ b/docs/reference/sboms-pbm.md @@ -0,0 +1,107 @@ +# Software Bill of Materials + +A Software Bill of Materials (SBOM) is a machine-readable inventory of the components and dependencies included in a software release. It helps you understand what is included in a build and assess potential security or compliance risks. + +Starting with version 2.15.0, every Percona Backup for MongoDB (PBM) release includes a [CycloneDX 1.6 :octicons-link-external-16:](https://cyclonedx.org/specification/overview/){:target="_blank"} SBOM in JSON format. + +## Why it matters + +An SBOM helps you: + +- Identify the components and dependencies included in a PBM release. +- Assess known vulnerabilities using SBOM-compatible security scanners. +- Support security reviews, compliance processes, and software supply chain requirements. +- Verify the contents of deployed software artifacts. + +## Where to find the SBOM + +| Distribution method | SBOM location | +|---|---| +| Binary tarball | `percona-backup-mongodb-{{release}}/percona-backup-mongodb-{{release}}.cdx.json` | +| RPM package | `/usr/share/doc/percona-backup-mongodb/percona-backup-mongodb-{{release}}.cdx.json` | +| DEB package | `/usr/share/doc/percona-backup-mongodb/percona-backup-mongodb-{{release}}.cdx.json` | +| Docker image | Embedded in the image and available as an attached OCI artifact. See [Docker images](#docker-images). | + + +## Verifying and scanning the SBOM + +The examples below use [Trivy :octicons-link-external-16:](https://trivy.dev/){:target="_blank"}. You can also use other CycloneDX-compatible scanners, such as [Grype :octicons-link-external-16:](https://github.com/anchore/grype){:target="_blank"} or Snyk. + +### Binary tarball + +```bash +# Confirm the SBOM is bundled +tar tzf percona-backup-mongodb-{{release}}-x86_64.tar.gz | grep cdx.json + +# Extract and scan +tar xzf percona-backup-mongodb-{{release}}-x86_64.tar.gz \ + -C /tmp percona-backup-mongodb-{{release}}/percona-backup-mongodb-{{release}}.cdx.json +trivy sbom --severity HIGH,CRITICAL --ignore-unfixed \ + /tmp/percona-backup-mongodb-{{release}}/percona-backup-mongodb-{{release}}.cdx.json +``` + +### RPM package + +```bash +# Confirm the package installs the SBOM +rpm -ql percona-backup-mongodb | grep cdx.json + +# Scan it (replace 9.x with your RHEL/OL version) +trivy sbom --severity HIGH,CRITICAL --ignore-unfixed --distro redhat/9.x \ + /usr/share/doc/percona-backup-mongodb/percona-backup-mongodb-{{release}}.cdx.json +``` + +### DEB package + +```bash +# Confirm the package installs the SBOM +dpkg -L percona-backup-mongodb | grep cdx.json + +# Scan it +trivy sbom --severity HIGH,CRITICAL --ignore-unfixed \ + /usr/share/doc/percona-backup-mongodb/percona-backup-mongodb-{{release}}.cdx.json +``` + +### Docker images + +Each PBM Docker image (Docker Hub `percona/percona-backup-mongodb`, PerconaLab `perconalab/percona-backup-mongodb`) ships with **two** CycloneDX 1.6 SBOMs that describe overlapping scopes: + +| SBOM | Scope | How to access | +|---|---|---| +| **Embedded** | PBM binary and Go modules only | Inside the image filesystem | +| **OCI-attached** | Full image — PBM and UBI9 base OS packages | Registry-side, via the OCI Referrers API | + +#### Scan via OCI Referrers API (recommended) + +`trivy image --sbom-sources oci` fetches the attached SBOM via the OCI Referrers API and scans it, without pulling the image: + +```bash +trivy image --severity HIGH,CRITICAL --ignore-unfixed --sbom-sources oci \ + docker.io/percona/percona-backup-mongodb:{{release}} +``` + + + +#### Scan the embedded SBOM + +To scan the embedded SBOM from inside the container image: + +```bash +docker run --rm -it --entrypoint cat \ + docker.io/percona/percona-backup-mongodb:{{release}} \ + /usr/share/doc/percona-backup-mongodb/percona-backup-mongodb-{{release}}.cdx.json \ + | trivy sbom --severity HIGH,CRITICAL --ignore-unfixed - +``` + +#### Advanced: Inspect OCI-attached SBOMs with ORAS + +You can use the [ORAS CLI :octicons-link-external-16:](https://oras.land/){:target="_blank"} to discover and download OCI-attached SBOMs. + +```bash +# Use the per-architecture tag to resolve directly to the image manifest +oras discover --format tree \ + docker.io/percona/percona-backup-mongodb:{{release}}-amd64 + +# Pull the SBOM artifact using the digest from the discover output +oras pull docker.io/percona/percona-backup-mongodb@sha256: +``` diff --git a/docs/release-notes.md b/docs/release-notes.md index 16d13361..43d70c14 100644 --- a/docs/release-notes.md +++ b/docs/release-notes.md @@ -1,4 +1,5 @@ # {{pbm.full_name}} release notes +* [{{pbm.full_name}} 2.15.0](release-notes/2.15.0.md) * [{{pbm.full_name}} 2.14.0](release-notes/2.14.0.md) * [{{pbm.full_name}} 2.13.0](release-notes/2.13.0.md) * [{{pbm.full_name}} 2.12.0](release-notes/2.12.0.md) diff --git a/docs/release-notes/2.13.0.md b/docs/release-notes/2.13.0.md index 41b68c77..2ce3f222 100644 --- a/docs/release-notes/2.13.0.md +++ b/docs/release-notes/2.13.0.md @@ -15,7 +15,7 @@ Percona Backup for MongoDB (PBM) is a distributed, low-impact solution for creat Workload Identity Federation lets on-premises or multicloud workloads access Google Cloud resources using federated identities instead of a service account key, eliminating the maintenance and security burden of service account keys. - For detailed information, refer to our comprehensive [documentation](https://docs.percona.com/percona-backup-mongodb/details/workload-identity-auth.html). + For detailed information, refer to our comprehensive [documentation](https://docs.percona.com/percona-backup-mongodb/2.14.0/details/workload-identity-auth.html). === "🔐 Selective backups" @@ -29,7 +29,7 @@ Percona Backup for MongoDB (PBM) is a distributed, low-impact solution for creat pbm backup --ns="mydb.*" --with-users-and-roles ``` - For detailed information about this feature, see our [documentation](https://docs.percona.com/percona-backup-mongodb/usage/backup-selective.html#selective-backup-with-users-and-roles). + For detailed information about this feature, see our [documentation](https://docs.percona.com/percona-backup-mongodb/2.14.0/usage/backup-selective.html#selective-backup-with-users-and-roles). ## Changelog diff --git a/docs/release-notes/2.14.0.md b/docs/release-notes/2.14.0.md index 48b16892..48909390 100644 --- a/docs/release-notes/2.14.0.md +++ b/docs/release-notes/2.14.0.md @@ -85,4 +85,3 @@ For users who are automating PBM operations, PBM CLI introduces the `-y` and `-- - [PBM-1657](https://perconadev.atlassian.net/browse/PBM-1657): Resolved an issue in the PBM CLI that prevented the correct parsing of `mongodb+srv` URIs and returned an inaccurate error message stating “**unescaped colon in password**”, although no colon was present. The CLI now properly parses `mongodb+srv` URIs and provides an accurate error message. - [PBM-1683](https://perconadev.atlassian.net/browse/PBM-1683): Fixed an issue where `pbm describe-backup` reported an incorrect, inflated value for `size_uncompressed_h` on non-base incremental backups. This field now accurately reflects the uncompressed size of the incremental data rather than cumulative or bloated values. - diff --git a/docs/release-notes/2.15.0.md b/docs/release-notes/2.15.0.md new file mode 100644 index 00000000..456eade9 --- /dev/null +++ b/docs/release-notes/2.15.0.md @@ -0,0 +1,67 @@ +# Percona Backup for MongoDB 2.15.0 ({{date.2_15_0}}) + +[Installation](../installation.md){.md-button} + +Percona Backup for MongoDB (PBM) is a distributed, low-impact solution for creating consistent backups of MongoDB sharded clusters and replica sets, and restoring them to a specific point in time. + +## Release highlights + +### Oracle Cloud Infrastructure support + +PBM now supports Oracle Cloud Infrastructure (OCI) Object Storage as a remote backup destination through a dedicated OCI-native driver. This integration enables seamless backup and restore operations across OCI environments. + +#### Authentication methods + +PBM supports multiple authentication mechanisms for OCI Object Storage, including Workload Identity authentication. This approach allows secure access to OCI resources without requiring API signing keys, reducing operational overhead and strengthening security. + +Supported authentication methods: + +- Choose **User Principal** when PBM runs on premises, on OCI, or in other cloud environments. +- Choose **Instance Principal** when PBM runs on OCI Compute instances. +- Choose **OKE Workload Identity** when PBM runs in Oracle Kubernetes Engine (OKE) enhanced clusters. + +#### Benefits + +- Secure access with OCI-native identity integration + +- Reduced operational overhead by eliminating manual credential management + +- Deployment flexibility across on-premises, cloud, and Kubernetes environments + +For detailed information on OCI, refer to our comprehensive [documentation](https://docs.percona.com/percona-backup-mongodb/2.15.0/details/oci-storage.html). + +### Software Bills of Materials (SBOMs) + +Percona Backup for MongoDB (PBM) now provides Software Bills of Materials (SBOMs). SBOMs improve transparency in the software supply chain by documenting the components and dependencies in a build. They are generated automatically as part of the release pipeline in the industry-standard `CycloneDX 1.6` format. + +SBOMs are distributed through the following channels: + +- **GitHub:** The latest SBOM is placed in the root of the [percona/percona-backup-mongodb](https://github.com/percona/percona-backup-mongodb) main branch. + +- **Binaries/Tarballs:** An SBOM file is included in the root directory of the release archive. + +- **Packages:** For `.deb` and `.rpm` packages, the SBOM file is installed in a standard documentation directory such as `/usr/share/doc/percona-backup-mongodb/`. + +- **Docker:** The SBOM is attached directly to the Docker image as metadata. + +If you want to dig deeper into this topic, refer to our [documentation](https://docs.percona.com/percona-backup-mongodb/2.15.0/reference/sboms-pbm.html). + +## Changelog + +### New features + +- [PBM-1727](https://perconadev.atlassian.net/browse/PBM-1727): Percona Backup for MongoDB (PBM) now supports OCI Object Storage as a remote backup destination through a dedicated OCI-native driver. +- [PBM-1728](https://perconadev.atlassian.net/browse/PBM-1728): Percona Backup for MongoDB (PBM) now supports multiple authentication methods for Oracle Cloud Infrastructure (OCI) Object Storage, including Workload Identity. +- [PBM-1710](https://perconadev.atlassian.net/browse/PBM-1710): Percona Backup for MongoDB (PBM) now provides Software Bills of Materials (SBOMs) for every release. + +### Improvements + +- [PBM-1370](https://perconadev.atlassian.net/browse/PBM-1370): Agent logs now include the reference date or interval supplied to cleanup commands. Previously, only the command receipt and epoch timestamp were recorded, making it difficult to determine which cleanup criteria were applied during troubleshooting and audit investigations. +- [PBM-1668](https://perconadev.atlassian.net/browse/PBM-1668): The restore command now accepts a `commitQuorum` option that controls when the primary commits an index during a restore operation. You can set this to `majority`, `votingMembers`, or a specific number of nodes. + Without this option, MongoDB defaults to `votingMembers`, which requires all data-bearing voting members to complete index building before the index is committed. In large replica sets, this can significantly delay restore operations if index creation is slow on even a subset of nodes. +- [PBM-1715](https://perconadev.atlassian.net/browse/PBM-1715): Physical backups and restores now support a `numParallelFiles` option that controls how many files PBM copies simultaneously during a backup operation. Increasing this value can improve backup performance on systems with high disk throughput. +- [PBM-1754](https://perconadev.atlassian.net/browse/PBM-1754): PBM now allows configuring the buffer size used during physical backup and restore operations. This enhancement provides greater flexibility for tuning memory usage and data transfer performance, enabling you to optimize backup and restore throughput based on your environment and workload requirements. + +### Fixed bugs + +- [PBM-1687](https://perconadev.atlassian.net/browse/PBM-1687): Fixed an issue where point-in-time recovery (PITR) was blocked when two backup commands were executed simultaneously. \ No newline at end of file diff --git a/docs/troubleshoot/pbm-pmm.md b/docs/troubleshoot/pbm-pmm.md index fb92ef68..4c86b60d 100644 --- a/docs/troubleshoot/pbm-pmm.md +++ b/docs/troubleshoot/pbm-pmm.md @@ -7,3 +7,4 @@ If you are facing issues with physical backups and restores via PMM, follow thes 3. Confirm that the system user who runs the `pbm-agent` process (by default, `mongod`) has the read / write access to both the MongoDB dbpath and the backup storage location. 4. Examine the `systemd` restart policy for the user mentioned in step 4. Ensure it is not set to `always` or `on-success`. During physical restores, the database must not be automatically restarted as this is controlled by the `pbm-agent`. + diff --git a/docs/usage/backup-physical.md b/docs/usage/backup-physical.md index 62f21db5..b2cd81dc 100644 --- a/docs/usage/backup-physical.md +++ b/docs/usage/backup-physical.md @@ -18,6 +18,26 @@ pbm backup --type=physical Starting with [2.4.0](../release-notes/2.4.0.md), PBM doesn't stop [point-in-time recovery oplog slicing](../features/point-in-time-recovery.md#oplog-slicing), if it's enabled, but runs it in parallel. This ensures [point-in-time recovery](pitr-tutorial.md) to any timestamp if it takes too long (e.g. hours) to make a backup snapshot. +## Parallel file copy for filesystem storage + +For physical backups stored on a filesystem, you can control how many files PBM processes in parallel during the backup operation. Increasing parallelism can improve performance by allowing multiple files to be copied simultaneously. + +To copy files in parallel, set `backup.numParallelFiles` in the PBM configuration: + +```yaml +backup: + numParallelFiles: 4 +``` + +Or pass `--num-parallel-files`: + +```sh +pbm backup --type=physical --num-parallel-files=4 +``` + +!!! note + Parallel file copy applies to **physical backups and incremental physical backups stored on filesystem only**. It has no effect on logical backups or on any S3-compatible storage, regardless of backup type. + ## Next steps [List backups](../usage/list-backup.md){.md-button} diff --git a/docs/usage/restore-physical.md b/docs/usage/restore-physical.md index 9b8c7569..0d169ced 100644 --- a/docs/usage/restore-physical.md +++ b/docs/usage/restore-physical.md @@ -126,7 +126,7 @@ restore: "node03:27017": /another/path/to/mongod ``` -When running physical restores in Docker environments, you need to include Percona Backup for MongoDB files together with your MongoDB binaries in the same container. See [Run Percona Backup for MongoDB in a Docker container](https://docs.percona.com/percona-backup-mongodb/install/docker.html) for more information. +When running physical restores in Docker environments, you need to include Percona Backup for MongoDB files together with your MongoDB binaries in the same container. See [Run Percona Backup for MongoDB in a Docker container](https://docs.percona.com/percona-backup-mongodb/2.15.0/install/docker.html) for more information. ### Parallel data download @@ -151,6 +151,25 @@ restore: * `maxDownloadBufferMb` - the maximum size of memory buffer to store the downloaded data chunks for decompression and ordering. It is calculated as `numDownloadWorkers * downloadChunkMb * 16` * `downloadChunkMb` is the size of the data chunk to download (by default, 32 MB) +### Parallel file copy for filesystem or NFS storage + +By default, PBM copies backup files sequentially during a physical restore from filesystem or NFS storage. On fast NFS mounts, this limits restore throughput regardless of available network bandwidth. + +To copy files in parallel, set `restore.numParallelFiles` in the PBM configuration: + +```yaml +restore: + numParallelFiles: 4 +``` + +Or pass `--num-parallel-files`: + +```sh +pbm restore --num-parallel-files=4 +``` + +!!! note + Parallel file copy applies to **physical restores from filesystem or NFS storage only**. It has no effect on logical restores or on S3-compatible storage. ## Next steps diff --git a/mkdocs-base.yml b/mkdocs-base.yml index 0774a511..2f80a788 100644 --- a/mkdocs-base.yml +++ b/mkdocs-base.yml @@ -8,7 +8,7 @@ copyright: > — Cookie Preferences repo_name: percona/pbm-docs repo_url: https://github.com/percona/pbm-docs -edit_uri: edit/main/docs/ +edit_uri: edit/2.15.0/docs/ use_directory_urls: false @@ -132,7 +132,7 @@ plugins: git-committers: enabled: !ENV [CI, false] repository: percona/pbm-docs - branch: "main" + branch: "2.15.0" tags: {} glightbox: {} open-in-new-tab: {} @@ -173,6 +173,11 @@ plugins: include_css: true enabled: true +extra: + version: + provider: mike +# homepage: https://docs.percona.com + nav: - Home: index.md - get-help.md @@ -237,6 +242,9 @@ nav: - Storage: - Remote backup storage overview: details/storage-configuration.md - AWS S3 storage: details/s3-storage.md + - Oracle Cloud Infrastructure (OCI) Object Storage: + - Overview: details/oci-storage.md + - Workload Identity authentication (OCI): details/oci-wif.md - details/minio.md - details/gcs.md - Workload Identity authentication: details/workload-identity-auth.md @@ -283,10 +291,13 @@ nav: - PBM control collections: details/control-collections.md - How PBM works: 'intro.md' - details/authentication.md + - details/pbm-user-roles.md + - Release notes: - release-notes.md - PBM 2.x: - - "{{pbm.full_name}} 2.14.0 ({{date.2_14_0}})": release-notes/2.14.0.md + - "{{pbm.full_name}} 2.15.0 ({{date.2_15_0}})": release-notes/2.15.0.md + - release-notes/2.14.0.md - release-notes/2.13.0.md - release-notes/2.12.0.md - release-notes/2.11.0.md @@ -333,8 +344,9 @@ nav: - 'Percona Backup for MongoDB 0.5.0 (2019-06-17)': 'release-notes/0.5.0.md' - Reference: - "About Percona Backup for MongoDB documentation": about-docs.md + - reference/sboms-pbm.md - reference/glossary.md - - Contribution guidelines: 'https://github.com/percona/pbm-docs/blob/main/CONTRIBUTING.md' + - Contribution guidelines: 'https://github.com/percona/pbm-docs/blob/2.15.0/CONTRIBUTING.md' - Copyright and licensing: copyright.md - Trademark policy: trademark-policy.md - Code of conduct: CODE_OF_CONDUCT.md diff --git a/mkdocs.yml b/mkdocs.yml index 72556c24..27a4dde2 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -2,7 +2,7 @@ INHERIT: mkdocs-base.yml -site_url: "https://docs.percona.com/percona-backup-mongodb" +site_url: "https://docs.percona.com/percona-backup-mongodb/2.15.0/" theme: diff --git a/variables.yml b/variables.yml index bbb63ab1..87282f08 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.14.0' -version: '2.14' +release: '2.15.0' +version: '2.15' year: '2026' pbm: full_name: 'Percona Backup for MongoDB' date: + 2_15_0: 2026-06-17 2_14_0: 2026-04-29 2_13_0: 2026-03-03 2_12_0: 2025-11-04