Google Cloud Storage (GCS)¶

You can use Google Cloud Storage (GCS) as a remote backup storage for Percona Backup for MongoDB.

Starting from version 2.10.0, PBM uses the Google Cloud SDK instead of AWS SDK. See how to adjust your PBM configuration to use GCS after the upgrade.

PBM supports communication with GCS via the JSON API and XML API. The preferred approach is to use the JSON API with a service account. HMAC keys are mainly useful for compatibility with S3-style APIs.

Known limitation

When you run backups to GCS via HMAC keys, incomplete backups may be incorrectly marked as successful if network interruptions occur during the backup process. This results in corrupted or partially uploaded archives being stored and treated as valid backups, which can later fail during restore operations. This issue is addressed in PBM-1605.

Until the issue is resolved, we recommend using a native GCS connection type with JSON keys rather than HMAC keys to ensure backup integrity.

To use GCS, you need the following:

create a service account
add keys for the service account:
- add JSON keys or
- add HMAC keys
create a bucket
add the GCS configuration to PBM

Create a bucket¶

Install and configure the gcloud CLI

Create a bucket

$ gcloud storage buckets create my-gcs-bucket --location=US

Verify the bucket creation
```
$ gcloud storage buckets list
```

After the bucket is created, apply the proper permissions for PBM to use the bucket.

Configuration example¶

You can find the configuration file template and uncomment the required fields.

using JSON keysusing HMAC keys

storage:
 type: gcs
 gcs:
     bucket: pbm-testing
     prefix: pbm/test
     credentials:
       clientEmail: <your-service-account-email-here>
       privateKey: <your-private-key-here>

storage:
 type: gcs
 gcs:
     bucket: pbm-testing
     prefix: pbm/test
     credentials:
       hmacAccessKey: <your-access-key-id-here>
       hmacSecret: <your-secret-key-here>

Debug logging¶

You can enable debug logging for different types of requests to GCS in Percona Backup for MongoDB. Percona Backup for MongoDB prints log messages in the pbm logs output so that you can debug and diagnose GCS request issues or failures.

To enable S3 debug logging, set the storage.gcs.debugTrace option in Percona Backup for MongoDB configuration. This instructs PBM to also print HTTP trace from the MinIO storage in the logs.

Adjust PBM configuration to use GCS¶

Starting with version 2.10.0, PBM uses the Google Cloud SDK instead of AWS SDK. If you are upgrading from an earlier version, you need to adjust your PBM configuration as follows:

Change the storage.type from s3 to gcs.
Change the storage.s3 section to storage.gcs and adjust the parameters accordingly. See the Configuration example above. Select the option depending on the authentication method you use.

Last update: October 30, 2025
Created: October 30, 2025