Oracle Cloud Infrastructure Object Storage

Percona Backup for MongoDB (PBM) supports OCI Object Storage 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 (see Workload Identity authentication)

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). See the OCI CLI documentation for installation instructions
• An OCI user with permission to create compartments, buckets, dynamic groups, and IAM policies in your tenancy
• An OCI API signing key pair: private key on the host running PBM, public key uploaded to the OCI user

Initialize the OCI CLI configuration if you have not done so already:

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:

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:

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:

oci iam region-subscription list \
  --region <HOME_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.

export HOME_REGION=<your-home-region>     # e.g. us-ashburn-1
export BUCKET_REGION=<your-bucket-region> # e.g. eu-frankfurt-1
export COMPARTMENT_NAME=pbm-backup
export BUCKET_NAME=<your-bucket-name>

Retrieve and export the values PBM requires:

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

Create a compartment for PBM backup resources:

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:

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:

oci os bucket create \
  --region "$BUCKET_REGION" \
  --namespace-name "$NAMESPACE" \
  --compartment-id "$COMPARTMENT_OCID" \
  --name "$BUCKET_NAME"

Verify the bucket was created:

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.

Two policies are required:

User access policy — grants your OCI user group permission to manage objects in the PBM compartment. Replace <OCI_GROUP_NAME> with the name of the group containing your PBM user:

oci iam policy create \
  --region "$HOME_REGION" \
  --compartment-id "$TENANCY_OCID" \
  --name pbm-user-access \
  --description "Allow PBM user group to manage backup objects" \
  --statements "[\"Allow group <OCI_GROUP_NAME> to manage object-family in compartment $COMPARTMENT_NAME\"]"

Native copy policy — grants the OCI Object Storage service permission to copy objects internally. PBM requires this for server-side copy operations:

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:

sed 's/^/          /' "$KEY_FILE"

Create the configuration file:

storage:
  type: oci
  oci:
    region: <BUCKET_REGION>
    namespace: <NAMESPACE>
    bucket: <BUCKET_NAME>
    prefix: pbm
    credentials:
      type: userPrincipal
      userPrincipal:
        tenancy: <TENANCY_OCID>
        user: <USER_OCID>
        fingerprint: <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:

sed 's/^/          /' "$KEY_FILE"

instancePrincipal

Use this when PBM runs on an OCI Compute instance. No API keys are required in the configuration file.

1. Create a dynamic group that includes the compute instance:

   oci iam dynamic-group create \
       --region "$HOME_REGION" \
       --compartment-id "$TENANCY_OCID" \
       --name pbm-instance-group \
       --description "PBM Compute instance principal" \
       --matching-rule "ANY {instance.id = '<INSTANCE_OCID>'}"
   

2. Create a policy granting the dynamic group access to the bucket:

   oci iam policy create \
       --region "$HOME_REGION" \
       --compartment-id "$TENANCY_OCID" \
       --name pbm-instance-policy \
       --description "Allow PBM instance to access backup bucket" \
       --statements "[\"Allow dynamic-group pbm-instance-group to manage objects \
       in compartment pbm-backup where target.bucket.name = '<BUCKET_NAME>'\"]"
   

3. Configure PBM:

   storage:
     type: oci
     oci:
       region: <BUCKET_REGION>
       namespace: <NAMESPACE>
       bucket: <BUCKET_NAME>
       prefix: pbm
       credentials:
         type: instancePrincipal
   

   Wait for a few minutes for IAM policy propagation before testing the configuration.

   Note

   IAM changes for dynamic groups can take 5 to 10 minutes to propagate. The native copy policy from the previous section is still required alongside the instance principal policy.

Apply the PBM configuration

Apply the configuration:

pbm config --file /path/to/oci-config.yaml

Force PBM to resync the storage configuration:

pbm config --force-resync

Verify the configuration

Verify all agents connected and storage initialized successfully:

pbm status

Output

$ 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://idvufsl0apl6/rasika-bucket/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:

pbm backup
pbm list

Output

    $ pbm backup
    Starting backup "2026-06-12T07:11:31Z".....
    Backup "2026-06-12T07:11:31Z" saved to remote store (path: "oci://idvufsl0apl6/rasika-bucket/pbm")

    $ 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 <off>:

---

Last update: June 12, 2026
Created: June 12, 2026