diff --git a/.gitignore b/.gitignore index 6260d046..a6f2d12b 100644 --- a/.gitignore +++ b/.gitignore @@ -16,6 +16,7 @@ styles/ # Allow !styles/config/vocabularies/Percona/** +.cache/ # Generated plugin cache .cache/plugin/git-committers/ diff --git a/docs/manage/automate-s3-access.md b/docs/manage/automate-s3-access.md index 44073a11..abde1016 100644 --- a/docs/manage/automate-s3-access.md +++ b/docs/manage/automate-s3-access.md @@ -1,14 +1,28 @@ # Automate access to S3 buckets for Percona Backup for MongoDB -When you run Percona Backup for MongoDB in AWS environment (on EC2 instances or using EKS), you can automate access to AWS S3 buckets for Percona Backup for MongoDB. Percona Backup for MongoDB uses the environment variables and metadata to access S3 buckets so that you don’t have to explicitly specify the S3 credentials in the PBM configuration file. Thereby you control the access to your cloud infrastructure from a single place. +When you run Percona Backup for MongoDB in an AWS environment, you can automate access to S3 buckets without storing credentials in the PBM configuration file. PBM uses AWS environment variables and instance metadata to authenticate, so you control access to your cloud infrastructure from a single place. + +Choose the method that matches your deployment: + +- **EC2 instances** — configure `pbm-agent` to assume an IAM role using the instance profile attached to the EC2 instance. +- **EKS (Kubernetes)** — use [IAM Roles for Service Accounts (IRSA)](#iam-roles-for-service-accounts-irsa), the recommended approach for pod-level AWS authentication on EKS. ## Assume a role from an EC2 instance -You can configure Percona Backup for MongoDB to assume an IAM role. To make this work, the `pbm-agent` leverages the AWS environment variables to assume the specified role. The steps are the following: +When `pbm-agent` runs on an EC2 instance, it can assume a target IAM role using the instance profile credentials. Set the `AWS_ROLE_ARN` environment variable to tell PBM which role to assume. + +### Prerequisites + +- AWS CLI installed and configured with permissions to create and attach IAM policies and roles +- An EC2 instance with an [IAM instance profile :octicons-link-external-16:](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html) attached +- The name and account ID of the EC2 instance role associated with that profile +- An S3 bucket for PBM backup storage -1. Ensure that the EC2 instance where `pbm-agent` is running has an [IAM instance profile :octicons-link-external-16:](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html) attached. The role associated with this instance profile must have a permissions policy that allows it to assume the target role. +### Steps - For example, if your target role is `arn:aws:iam::TARGET_ACCOUNT_ID:role/pbm-target-role`, create a policy with the following content and attach it to your EC2 instance role: +1. Ensure that the EC2 instance where `pbm-agent` is running has an [IAM instance profile :octicons-link-external-16:](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html) attached. The role associated with this instance profile must have a permissions policy that allows it to assume the target role. + + Create a file named `pbm-assume-role-policy.json` with the following content, replacing `TARGET_ACCOUNT_ID` and `pbm-target-role` with your target account ID and role name: ```json { @@ -22,214 +36,255 @@ You can configure Percona Backup for MongoDB to assume an IAM role. To make this ] } ``` - > Remember to replace `TARGET_ACCOUNT_ID` and `pbm-target-role` with your actual target account ID and role name. -2. Create the target IAM role that PBM will assume. This involves setting up a trust relationship and attaching the necessary S3 permissions. + Create the IAM policy and attach it to the EC2 instance role, replacing `EC2_ACCOUNT_ID` and `pbm-ec2-instance-role` with your values: - * **Trust Policy**: The trust policy of the target role must allow the EC2 instance's role to assume it. + ```bash + aws iam create-policy \ + --policy-name pbm-assume-role-policy \ + --policy-document file://pbm-assume-role-policy.json - For example, if your EC2 instance role is `arn:aws:iam::EC2_ACCOUNT_ID:role/pbm-target-role`, use the following trust policy for your target role: + aws iam attach-role-policy \ + --role-name pbm-ec2-instance-role \ + --policy-arn arn:aws:iam::EC2_ACCOUNT_ID:policy/pbm-assume-role-policy + ``` - ```json - { - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Principal": { - "AWS": "arn:aws:iam::EC2_ACCOUNT_ID:role/pbm-target-role" - }, - "Action": "sts:AssumeRole" - } - ] - } - ``` - > Remember to replace `EC2_ACCOUNT_ID` and `pbm-target-role` with the account ID and role name of your EC2 instance. +2. Create the target IAM role that PBM will assume. This involves setting up a trust relationship and attaching the necessary S3 permissions. - * **Permissions Policy**: The target role must have a permissions policy attached that grants the necessary S3 access for PBM. + **Trust policy** — allows the EC2 instance role to assume the target role. - Here is an example policy that grants the required permissions. Attach it to your target role: + Create a file named `pbm-target-trust-policy.json` with the following content, replacing `EC2_ACCOUNT_ID` and `pbm-ec2-instance-role` with the account ID and role name of your EC2 instance: - ```json - { - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": [ - "s3:GetObject", - "s3:PutObject", - "s3:DeleteObject", - "s3:GetBucketLocation" - ], - "Resource": "arn:aws:s3:::your-pbm-bucket/*" + ```json + { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Principal": { + "AWS": "arn:aws:iam::EC2_ACCOUNT_ID:role/pbm-ec2-instance-role" }, - { - "Effect": "Allow", - "Action": "s3:ListBucket", - "Resource": "arn:aws:s3:::your-pbm-bucket" - } - ] - } - ``` - > Remember to replace `your-pbm-bucket` with the name of your S3 bucket. + "Action": "sts:AssumeRole" + } + ] + } + ``` + + Create the target IAM role: + + ```bash + aws iam create-role \ + --role-name pbm-target-role \ + --assume-role-policy-document file://pbm-target-trust-policy.json + ``` -3. Set the `AWS_ROLE_ARN` environment variable to the ARN of the target role in the environment where you start the `pbm-agent` process. You can also set `AWS_SESSION_NAME` (optional, but recommended for audit trails). + **Permissions policy** — grants the target role the S3 access that PBM requires. + + Create a file named `pbm-s3-policy.json` with the following content, replacing `your-pbm-bucket` with your S3 bucket name: + + ```json + { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "s3:GetObject", + "s3:PutObject", + "s3:DeleteObject" + ], + "Resource": "arn:aws:s3:::your-pbm-bucket/*" + }, + { + "Effect": "Allow", + "Action": [ + "s3:ListBucket", + "s3:GetBucketLocation" + ], + "Resource": "arn:aws:s3:::your-pbm-bucket" + } + ] + } + ``` + + Create the IAM policy and attach it to the target role, replacing `TARGET_ACCOUNT_ID` with your target account ID: + + ```bash + aws iam create-policy \ + --policy-name pbm-s3-access-policy \ + --policy-document file://pbm-s3-policy.json + + aws iam attach-role-policy \ + --role-name pbm-target-role \ + --policy-arn arn:aws:iam::TARGET_ACCOUNT_ID:policy/pbm-s3-access-policy + ``` + +3. Set the `AWS_ROLE_ARN` environment variable to the ARN of the target role in the environment where you start the `pbm-agent` process. Setting `AWS_ROLE_SESSION_NAME` is optional but recommended for audit trails. ```bash export AWS_ROLE_ARN=arn:aws:iam::ACCOUNT_ID:role/pbm-target-role - export AWS_SESSION_NAME=pbm-session-$(hostname) + export AWS_ROLE_SESSION_NAME=pbm-session-$(hostname) ``` -4. In the [PBM in a config file](../install/backup-storage.md) provide remote storage information, but leave the `s3.credentials` section empty. PBM will use the assumed role's credentials. +4. In the [PBM configuration](../install/backup-storage.md), provide the remote storage information but leave the `s3.credentials` section empty. PBM uses the assumed role’s credentials automatically. ```yaml storage: type: s3 s3: - region: - bucket: + region: + bucket: ``` -!!! note - - When `AWS_ROLE_ARN` is set, the credentials from the assumed role take precedence over the EC2 instance profile's credentials. However, if you specify `s3.credentials` in the PBM configuration file, they will override any other IAM-based credentials. +5. Restart the `pbm-agent` process to apply the new environment variables. +!!! note -5. Restart the `pbm-agent` process. + When `AWS_ROLE_ARN` is set, the credentials from the assumed role take precedence over the EC2 instance profile’s credentials. If you explicitly specify `s3.credentials` in the PBM configuration file, those credentials override any IAM-based authentication. !!! admonition "See also" AWS documentation: [How can I grant my Amazon EC2 instance access to an Amazon S3 bucket? :octicons-link-external-16:](https://aws.amazon.com/premiumsupport/knowledge-center/ec2-instance-access-s3-bucket/) - + ## IAM Roles for Service Accounts (IRSA) !!! admonition "Version added: 2.0.3" -[IRSA :octicons-link-external-16:](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html) is the native way for AWS EKS (Amazon Elastic Kubernetes Service) to allow applications running in pods to access the AWS API, using permissions configured in AWS IAM roles. This is the recommended approach for granting S3 access to Percona Backup for MongoDB in an EKS environment. +[IRSA :octicons-link-external-16:](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html) is the native AWS EKS mechanism for granting pods access to the AWS API using IAM roles. It is the recommended approach for granting S3 access to PBM in an EKS environment. -To configure IRSA for PBM, follow these steps: +### Prerequisites -1. Set up an OIDC provider for your EKS cluster +- AWS CLI and `kubectl` configured with access to your cluster +- `eksctl` installed (used to associate the OIDC provider) -IRSA requires an OpenID Connect (OIDC) provider to be associated with your cluster. +### Steps -First, check if you already have an OIDC provider. Replace `` with your EKS cluster's name. -```bash -aws eks describe-cluster --name --query "cluster.identity.oidc.issuer" --output text -``` -If the command returns a URL, your OIDC provider is already set up. If not, create one using `eksctl`. Replace `` and `` with your cluster's region and name. -```bash -eksctl utils associate-iam-oidc-provider --region --cluster --approve -``` +1. **Set up an OIDC provider for your EKS cluster.** -2. Create an IAM policy for S3 access + IRSA requires an OpenID Connect (OIDC) provider associated with your cluster. Check whether one already exists: -This policy defines the permissions that PBM needs to access your S3 bucket. + ```bash + aws eks describe-cluster --name --query "cluster.identity.oidc.issuer" --output text + ``` -Create a JSON file (e.g., `pbm-s3-policy.json`) with the following content. Remember to replace `your-pbm-bucket` with your actual bucket name. -```json -{ - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": [ - "s3:GetObject", - "s3:PutObject", - "s3:DeleteObject", - "s3:GetBucketLocation" - ], - "Resource": "arn:aws:s3:::your-pbm-bucket/*" - }, - { - "Effect": "Allow", - "Action": "s3:ListBucket", - "Resource": "arn:aws:s3:::your-pbm-bucket" - } - ] -} -``` + If the command returns a URL, the OIDC provider is already configured. If not, create one: + + ```bash + eksctl utils associate-iam-oidc-provider --region --cluster --approve + ``` -Now, create the IAM policy using the AWS CLI. -```bash -aws iam create-policy --policy-name pbm-s3-access-policy --policy-document file://pbm-s3-policy.json -``` + Note the OIDC issuer URL — you will need the ID at the end of the URL in subsequent steps. For example, if the URL is `https://oidc.eks.us-west-2.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE`, the OIDC ID is `EXAMPLED539D4633E53DE1B71EXAMPLE`. -3. Create an IAM role +2. **Create an IAM policy for S3 access.** -This role will be assumed by the Kubernetes service account used by your PBM pods. + This policy defines the permissions PBM needs to access your S3 bucket. Create a file named `pbm-s3-policy.json` with the following content, replacing `your-pbm-bucket` with your actual bucket name: -First, create a trust policy JSON file (e.g., `pbm-trust-policy.json`). This policy allows your Kubernetes service account to assume the role. Replace ``, ``, and `` with your AWS account ID, EKS cluster region, and the OIDC ID from step 1. -```json -{ - "Version": "2012-10-17", - "Statement": [ + ```json { - "Effect": "Allow", - "Principal": { - "Federated": "arn:aws:iam:::oidc-provider/oidc.eks..amazonaws.com/id/" - }, - "Action": "sts:AssumeRoleWithWebIdentity", - "Condition": { - "StringEquals": { - "oidc.eks..amazonaws.com/id/:aud": "sts.amazonaws.com", - "oidc.eks..amazonaws.com/id/:sub": "system:serviceaccount::" + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "s3:GetObject", + "s3:PutObject", + "s3:DeleteObject" + ], + "Resource": "arn:aws:s3:::your-pbm-bucket/*" + }, + { + "Effect": "Allow", + "Action": [ + "s3:ListBucket", + "s3:GetBucketLocation" + ], + "Resource": "arn:aws:s3:::your-pbm-bucket" + } + ] + } + ``` + + Create the IAM policy: + + ```bash + aws iam create-policy --policy-name pbm-s3-access-policy --policy-document file://pbm-s3-policy.json + ``` + +3. **Create an IAM role with a trust policy.** + + This role will be assumed by the Kubernetes service account used by your PBM pods. Create a trust policy file named `pbm-trust-policy.json`, replacing ``, ``, ``, ``, and `` with your values: + + ```json + { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Principal": { + "Federated": "arn:aws:iam:::oidc-provider/oidc.eks..amazonaws.com/id/" + }, + "Action": "sts:AssumeRoleWithWebIdentity", + "Condition": { + "StringEquals": { + "oidc.eks..amazonaws.com/id/:aud": "sts.amazonaws.com", + "oidc.eks..amazonaws.com/id/:sub": "system:serviceaccount::" + } + } } - } + ] } - ] -} -``` -> **Note:** Replace `` and `` with the namespace and name of the service account your PBM pods will use. + ``` + + Create the IAM role: + + ```bash + aws iam create-role --role-name pbm-s3-access-role --assume-role-policy-document file://pbm-trust-policy.json + ``` + +4. **Attach the S3 policy to the role.** + + Replace `` with your AWS account ID: + + ```bash + aws iam attach-role-policy --role-name pbm-s3-access-role --policy-arn arn:aws:iam:::policy/pbm-s3-access-policy + ``` -Create the IAM role: -```bash -aws iam create-role --role-name pbm-s3-access-role --assume-role-policy-document file://pbm-trust-policy.json -``` +5. **Annotate the Kubernetes service account.** -4. Attach the policy to the role + Associate the IAM role with the Kubernetes service account that your `pbm-agent` pods use. First, retrieve the role ARN: -Attach the S3 access policy you created in step 2 to the role you created in step 3. Replace `` with your AWS account ID. -```bash -aws iam attach-role-policy --role-name pbm-s3-access-role --policy-arn arn:aws:iam:::policy/pbm-s3-access-policy -``` + ```bash + aws iam get-role --role-name pbm-s3-access-role --query "Role.Arn" --output text + ``` -5. Annotate the Kubernetes service account + Then annotate the service account, replacing ``, ``, and `` with the correct values: -Now, you need to associate the IAM role with the Kubernetes service account that your `pbm-agent` pods use. This is done by annotating the service account. + ```bash + kubectl annotate serviceaccount -n \ + eks.amazonaws.com/role-arn="" + ``` -First, get the ARN of the role you created: -```bash -aws iam get-role --role-name pbm-s3-access-role --query "Role.Arn" --output text -``` + If your pods are already running, restart them to apply the changes and inject the AWS environment variables. -Then, annotate the service account. Replace ``, ``, and `` with the correct values. -```bash -kubectl annotate serviceaccount -n \ - eks.amazonaws.com/role-arn="" -``` -If your pods are already running, you will need to restart them to apply the changes and inject the AWS environment variables. +6. **Configure PBM storage.** -6. Configure PBM storage + In the [PBM configuration](../install/backup-storage.md), specify the S3 storage without credentials. PBM automatically uses the credentials provided by IRSA: -Finally, configure your PBM storage to use S3, but do not provide any credentials. PBM will automatically use the credentials provided by IRSA. + ```yaml + storage: + type: s3 + s3: + region: + bucket: + ``` -Your storage configuration should look like this: -```yaml -storage: - type: s3 - s3: - region: - bucket: -``` +!!! note -!!! note - If IRSA-related credentials are defined, they have priority over any IAM instance profile. However, if you intentionally specify S3 credentials in the PBM configuration file, they override any IRSA/IAM instance profile related credentials and are used for authentication instead. + IRSA credentials take priority over any IAM instance profile. If you explicitly specify `s3.credentials` in the PBM configuration file, those credentials override both IRSA and IAM instance profile authentication. !!! admonition "See also" - AWS documentation: + AWS documentation: * [Introducing fine-grained IAM roles for service accounts :octicons-link-external-16:](https://aws.amazon.com/blogs/opensource/introducing-fine-grained-iam-roles-service-accounts/) * [How do I use the IAM roles for service accounts (IRSA) feature with Amazon EKS to restrict access to an Amazon S3 bucket? :octicons-link-external-16:](https://aws.amazon.com/premiumsupport/knowledge-center/eks-restrict-s3-bucket/) diff --git a/docs/usage/oplog-replay.md b/docs/usage/oplog-replay.md index a06141e5..4e858b1e 100644 --- a/docs/usage/oplog-replay.md +++ b/docs/usage/oplog-replay.md @@ -1,17 +1,19 @@ # Replay oplog from arbitrary start time -You can replay the [oplog](../reference/glossary.md#oplog) for a specific period on top of any backup: logical, physical, storage level snapshot (like [EBS-snapshot](../reference/glossary.md#ebs-snapshot)). You can save oplog slices without the mandatory base backup snapshot. This behavior is controlled by the [`pitr.oplogOnly`](../reference/pitr-options.md) configuration parameter: +You can have PBM save oplog slices without the mandatory base backup snapshot. This behavior is controlled by the [`pitr.oplogOnly`](../reference/pitr-options.md) configuration parameter: ```yaml pitr: oplogOnly: true ``` -By replaying these oplog slices on top of the backup snapshot with the [`pbm oplog-replay`](../reference/pbm-commands.md#pbm-oplog-replay) command, you can manually restore sharded clusters and non-sharded replica sets to a specific point in time from a backup made by any tool and not only by Percona Backup for MongoDB. Plus, you reduce time, storage space, and administration efforts on making the redundant base backup snapshot. +You can then replay the [oplog](../reference/glossary.md#oplog) for a specific period on top of any backup: logical, physical, storage-level snapshot (like [EBS-snapshot](../reference/glossary.md#ebs-snapshot)). + +By replaying these oplog slices on top of a backup snapshot with the [`pbm oplog-replay`](../reference/pbm-commands.md#pbm-oplog-replay) command, you can manually restore sharded clusters and non-sharded replica sets to a specific point in time from a backup made by any tool and not only by Percona Backup for MongoDB. Plus, you reduce time, storage space, and administration efforts on making the redundant base backup snapshot. !!! warning - Use the oplog replay functionality with caution, only when you are sure about the starting time from which to replay oplog. The oplog replay does not guarantee data consistency when restoring from any backup. However, it is less error-prone for backups made with Percona Backup for MongoDB. + Use the oplog replay functionality with caution, only when you are sure about the starting time from which to replay oplog. ## Ways to specify time for oplog replay @@ -29,11 +31,11 @@ You can define the oplog replay stop point in two ways: !!! note "" - Starting with version 2.2.0, oplog replay on top of a physical backups made with Percona Backup for MongoDB is done automatically as part of [point-in-time recovery](pitr-physical.md). + Starting with version 2.2.0, oplog replay on top of physical backups made with Percona Backup for MongoDB is done automatically as part of [point-in-time recovery](pitr-physical.md). -This section describes how to **manually** replay oplog on top of physical backups made with Percona Backup for MongoDB version 2.1.0 and earlier. +This section describes how to **manually** replay oplog on top of physical backups. This is useful for backups made with Percona Backup for MongoDB version 2.1.0 and earlier, where oplog apply was not automatically done by PBM. -After you [restored a physical backup](restore.md), do the following: +After you [restore a physical backup](restore-physical.md), do the following: 1. Stop point-in-time recovery, if enabled, to release the lock. @@ -57,24 +59,30 @@ After you [restored a physical backup](restore.md), do the following: 4. After the oplog replay, make a fresh backup and enable the point-in-time recovery oplog slicing. -## Oplog replay for storage level snapshots +## Oplog replay for storage-level snapshots + +This section describes how to **manually** replay oplog on top of snapshot backups. -When making a backup, Percona Backup for MongoDB stops the point-in-time recovery. This is done to maintain data consistency after the restore. +After you [restore a snapshot backup](restore-external.md), do the following: -Storage-level snapshots are saved with point-in-time recovery enabled. Thus, after the database restore from such a backup, point-in-time recovery is automatically enabled and starts oplog slicing. These new oplog slices might conflict with the existing oplogs saved during the backup. To replay the oplog in such a case, do the following after the restore: +1. Start all `mongod` nodes +2. Start all `pbm-agents` -1. Disable point-in-time recovery. -2. Delete the oplog slices that might have been created. -3. Re-sync the data from the storage. -4. Run the `pbm oplog-replay` command and specify the `--start` and `--end` flags with the timestamps. +3. Run the following command to resync the backup list with the storage: ```bash - pbm oplog-replay --start="2022-01-02T15:00:00" --end="2022-01-03T15:00:00" - ``` + pbm config --force-resync + ``` -5. After the oplog replay, make a fresh backup and enable the point-in-time recovery oplog slicing. +4. Run the `pbm oplog-replay` command and specify the `--start` and `--end` flags. Use the `last_write_time` from the output of `pbm describe-backup` as the start. See [how you can specify the time](#ways-to-specify-time-for-oplog-replay). -[Known limitations](../features/known-limitations.md#oplog-replay-from-arbitrary-start-time){.md-button} + ```bash + pbm oplog-replay --start="2026-01-02T15:00:00" --end="2026-01-03T15:00:00" + ``` + +5. Start the balancer and start `mongos` nodes. +6. Make a fresh backup to serve as the new base for future restores. +[Known limitations](../features/known-limitations.md#oplog-replay-from-arbitrary-start-time){.md-button} diff --git a/docs/usage/restore-external.md b/docs/usage/restore-external.md index 6fc93f58..aca01b32 100644 --- a/docs/usage/restore-external.md +++ b/docs/usage/restore-external.md @@ -40,7 +40,7 @@ The following procedure describes the restore process from backups [made through pbm restore-finish -c ``` - At this stage, Percona Backup for MongoDB reads the metadata from the backup, prepares the data for the cluster / replica set start and ensures its consistency. The database is restored to the timestamp specified in the `restore_to_time` of the metadata. + At this stage, Percona Backup for MongoDB reads the metadata from the backup, prepares the data for the cluster / replica set start and ensures its consistency. The database is restored to the timestamp specified in the `last_write_time` of the metadata. !!! note @@ -67,9 +67,15 @@ After the restore is complete, do the following: pbm config --force-resync ``` -4. Start the balancer and start `mongos` nodes. +4. Optional. Perform point in time recovery by running [`pbm oplog-replay`](./oplog-replay.md#oplog-replay-for-storage-level-snapshots) using the `last_write_time` as the start, for example: -5. Make a fresh backup to serve as the new base for future restores. + ```bash + pbm oplog-replay --start="2026-01-02T15:00:00" --end="2026-01-03T15:00:00" + ``` + +5. Start the balancer and start `mongos` nodes. + +6. Make a fresh backup to serve as the new base for future restores. ### Restore from a backup made outside PBM @@ -83,7 +89,7 @@ After the restore is complete, do the following: To restore an external backup made without PBM, you need to specify the following for the `pbm restore` command: -* a path to the configuration file of the `mongod` node on the source cluster from where the backup was made. This is the configuration file that PBM will use during the restore. It should contain the [storage options :octicons-link-external-16:](https://www.mongodb.com/docs/manual/reference/configuration-options/#storage-options ) per replica set name, for example: +* a path to the configuration file of the `mongod` node on the source cluster from where the backup was made. This is the configuration file that PBM will use during the restore. It should contain the [storage options :octicons-link-external-16:](https://www.mongodb.com/docs/manual/reference/configuration-options/#storage-options) per replica set name, for example: ```yaml rs1: diff --git a/docs/usage/restore-physical.md b/docs/usage/restore-physical.md index 0d169ced..36e215cf 100644 --- a/docs/usage/restore-physical.md +++ b/docs/usage/restore-physical.md @@ -4,7 +4,7 @@ ## Considerations -1. Disable point-in-time recovery. A restore and point-in-time recovery oplog slicing are incompatible operations and cannot be run simultaneously. +1. Disable point-in-time recovery. Restore and point-in-time recovery oplog slicing operations are incompatible with each other and cannot be run simultaneously. ```bash pbm config --set pitr.enabled=false @@ -13,7 +13,7 @@ 2. The Percona Server for MongoDB version for both backup and restore data must be within the same major release. 3. Make sure all nodes in the cluster are healthy (i.e. report either PRIMARY or SECONDARY). Each `pbm-agent` needs to be able to connect to its local node and run queries in order to perform the restore. 4. For PBM versions before 2.1.0, physical restores are not supported for deployments with arbiter nodes. -5. At the end of a physical restore the database will be left down by `pbm-agent`. See the [Post-restore steps](#post-restore-steps) for instructions to resume normal operations. +5. After a physical restore completes, the database remains offline because it is intentionally left down by `pbm-agent`. To bring the database back to normal operation, follow the steps in [Post-restore steps](#post-restore-steps). ## Before you start @@ -38,6 +38,12 @@ ## Restore a database +!!! warning + + If Encryption at Rest is enabled, the restore requires access to the same encryption key that was active when the backup was taken. + - For manually managed key files, update mongod.conf on all nodes to point to the original key before starting the restore procedure. + - For Hashicorp Vault-managed keys, ensure the historical key version is still available inside Vault. No changes to mongod.conf are required. + 1. List the backups ```bash @@ -132,7 +138,7 @@ When running physical restores in Docker environments, you need to include Perco !!! admonition "Version added: [2.1.0](../release-notes/2.1.0.md)" -Percona Backup for MongoDB downloads data chunks from the S3 storage concurrently during physical restore. Read more about benchmarking results in the [Speeding up MongoDB restores in PBM](https://www.percona.com/blog/speeding-up-database-restores-in-pbm) blog post by *Andrew Pogrebnoi*. +Percona Backup for MongoDB downloads data chunks from S3 storage concurrently during physical restores, improving restore performance. For benchmarking results and implementation details, see the blog post [Speeding up MongoDB Restores in Percona Backup for MongoDB](https://www.percona.com/blog/speeding-up-restores-in-percona-backup-for-mongodb/) by *Andrew Pogrebnoi*. Here's how it works: diff --git a/mkdocs-base.yml b/mkdocs-base.yml index 2f80a788..2041b35c 100644 --- a/mkdocs-base.yml +++ b/mkdocs-base.yml @@ -153,7 +153,6 @@ plugins: css_dir: css javascript_dir: js canonical_version: null - print-site: add_to_navigation: false print_page_title: 'Percona Backup for MongoDB documentation'