Google Cloud storage¶

To use Google Cloud Storage (GCS) as an object store for backups, you need the following:

A GCS bucket name. Refer to the GCS bucket naming guidelines for bucket name requirements
Authentication to the bucket. See Choose the authentication method for available options.

Choose the authentication method¶

You can use one of the following options to authenticate to GCS:

Workload Identity (recommended on GKE). Bind a Google service account to the Kubernetes Service Account used by your database Pods. You do not store service account JSON keys in a Kubernetes Secret. Google provides short-lived credentials automatically. This is the recommended approach on Google Kubernetes Engine (GKE) and for environments that forbid exporting service account keys.
Service account JSON keys. Store the service account email and private key in a Kubernetes Secret and reference it in your cluster configuration. This method works on any Kubernetes platform and requires that you manage the credentials yourself.

Note

You can still use the S3-compatible implementation of GCS with HMAC keys. Refer to the Amazon S3 storage setup section for steps.

However, we don’t recommend their usage due to a known issue in PBM and encourage you to use the native gcs storage type instead.

How the Operator chooses GCS authentication¶

If a Secret with GCS credentials is defined in the Custom Resource (gcs.credentialsSecret), the Operator uses those credentials.
If gcs.credentialsSecret is omitted, the Operator configures Percona Backup for MongoDB to use Application Default Credentials (ADC), such as GKE Workload Identity.

Automate access to Google Cloud Storage using Workload Identity¶

Version added: 1.23.0

GKE Workload Identity lets Pods authenticate to Google Cloud as a Google service account. Percona Backup for MongoDB uses Application Default Credentials and receives short-lived tokens automatically. For how PBM uses Workload Identity and ADC, see the PBM documentation .

Prerequisites¶

Before you start, make sure you have the following:

A GKE cluster with Workload Identity enabled and the Operator and database deployed. See also Install on GKE.
A GCS bucket for backups
The Google Cloud CLI (gcloud) and kubectl installed and configured
Permission to create service accounts and manage IAM bindings

Set environment variables for the commands below. Replace the placeholders with your values:

export PROJECT_ID=<my-project-id>
export GCS_BUCKET=<my-backup-bucket>
export GSA_NAME=<my-gcs-backup-gsa>
export NAMESPACE=<my-namespace>
export KSA_NAME=default

KSA_NAME is the Kubernetes Service Account used by your database Pods. By default this is default. You can override it with the serviceAccountName Custom Resource option in the replsets, sharding.configsvrReplSet, and sharding.mongos subsections of the deploy/cr.yaml manifest.

Configure Google Cloud access¶

Create a Google service account (GSA), if you don’t have one already:

gcloud iam service-accounts create $GSA_NAME \
  --project=$PROJECT_ID \
  --display-name="Percona MongoDB GCS backups"

Grant the GSA permissions on the backup bucket. For example, grant object read and write access:
```
gcloud storage buckets add-iam-policy-binding gs://$GCS_BUCKET \
  --member="serviceAccount:${GSA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role="roles/storage.objectUser"
```
Tip

Choose the IAM role that matches your security policy. roles/storage.objectUser is a common choice for backup and restore workflows.

Allow the Kubernetes Service Account to impersonate the Google service account:

gcloud iam service-accounts add-iam-policy-binding \
  ${GSA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com \
  --role roles/iam.workloadIdentityUser \
  --member "serviceAccount:${PROJECT_ID}.svc.id.goog[${NAMESPACE}/${KSA_NAME}]"

Annotate the Kubernetes Service Account with the Google service account email:

kubectl -n $NAMESPACE annotate serviceaccount $KSA_NAME \
  iam.gke.io/gcp-service-account=${GSA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com \
  --overwrite

Annotating a Service Account does not restart existing Pods automatically. Restart the database Pods so they pick up the Workload Identity configuration. For a replica set named rs0, run the following:
```
export DBCLUSTER=my-cluster-name
kubectl rollout restart sts/$DBCLUSTER-rs0 -n $NAMESPACE
```

Configure Percona Server for MongoDB cluster¶

Now you are ready to configure Percona Server for MongoDB to use Workload Identity for GCS backups.

A new cluster deploymentExisting cluster

Edit the backup.storages subsection in the deploy/cr.yaml Custom Resource manifest. Give your storage a name and set the following keys:
- type - make sure the type is gcs
- bucket - where the data will be stored
- prefix (optional) - a path (sub-folder) inside the GCS bucket where backups will be stored. If you don’t set a prefix, backups are stored in the root directory.
- Omit gcs.credentialsSecret so that PBM uses Workload Identity / ADC to access the GCS storage.
Here’s the example configuration:
```
...
backup:
  enabled: true
  ...
  storages:
    gcs-wi:
      type: gcs
      gcs:
        bucket: <my-backup-bucket>
        prefix: mongodb-backup
...
```
For more storage options, see the Operator Custom Resource options.

Apply the configuration and deploy the cluster:

kubectl apply -f deploy/cr.yaml -n $NAMESPACE

Wait for the cluster to report the Ready status:
```
kubectl get psmdb -n $NAMESPACE
```

If your running Percona Server for MongoDB cluster is currently using a Kubernetes Secret with GCS credentials for backups, you can switch to Workload Identity by following these steps:

Configure Google Cloud access and annotate the Service Account, if you haven’t done it before.
Make a rolling restart of the database Pods so they pick up the Workload Identity annotation.
- Export the cluster name as an environment variable:
```
export DBCLUSTER=my-cluster-name
```
- Restart the Pods:
```
kubectl rollout restart sts/$DBCLUSTER-rs0 -n $NAMESPACE
```
Remove the credentials Secret from the Custom Resource. The storage name in the following command is gcs. Replace it with your value if you use another name:
```
kubectl -n $NAMESPACE patch psmdb $DBCLUSTER --type=json \
  -p '[{"op":"remove","path":"/spec/backup/storages/gcs/gcs/credentialsSecret"}]'
```

Verify access to GCS using Workload Identity¶

Run an on-demand backup to confirm that the cluster can write to the GCS bucket.

Troubleshooting¶

Confirm the Service Account annotation. The Kubernetes Service Account used by the database Pods must have the iam.gke.io/gcp-service-account annotation set to the Google service account email.
Confirm the IAM binding. The Google service account must grant roles/iam.workloadIdentityUser to serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE/KSA_NAME].
Confirm bucket permissions. The Google service account must have permission to read and write objects in the backup bucket.
Remove credentialsSecret. If gcs.credentialsSecret is still set in the Custom Resource, the Operator uses the Secret instead of Workload Identity.
Restart Pods after annotation changes. Existing Pods do not pick up a new Workload Identity annotation until you restart them.

Set up Google Cloud Storage access with service account keys¶

Follow these steps to authenticate using a service account JSON key. This method works on any Kubernetes environment.

Configuration steps

Create a service account , if you don’t have it already.
Add JSON service keys for the service account . As the result a service account key file in JSON format with the private key and related information is automatically downloaded on your machine.
Encode your keys in base64 format. You need to encode the service account email and the private key. You can get these values from the service account key file you downloaded when you created the service account keys.

The following command shows how to encode a private key. Replace the placeholder with your private key and service account email:
```
echo -n "-----BEGIN PRIVATE KEY-----\nPRIVATE_KEY\n-----END PRIVATE KEY-----\n" | base64
```

Create the Kubernetes Secret configuration file and specify the encoded GCS credentials within:

gcp-cs-secret.yaml

apiVersion: v1
kind: Secret
metadata:
  name: gcp-cs-secret-key
type: Opaque
data:
  GCS_CLIENT_EMAIL: base_64_encoded_email
  GCS_PRIVATE_KEY: base_64_encoded_key

Create the Kubernetes Secrets object. Replace the <namespace> placeholder with your value:
```
kubectl apply -f gcp-cs-secret.yaml -n <namespace>
```
Configure the GCS storage in the deploy/cr.yaml Custom Resource. Specify the following information:
- Set storages.NAME.type to gcs (substitute the NAME part with some arbitrary name you will later use to refer this storage when making backups and restores).
- Specify the bucket name for the storages.NAME.gcs.bucket option
- Specify the Secrets object name you created for the storages.NAME.gcs.credentialsSecret option
```
backup:
  storages:
    gcp-cs:
      type: gcs
      gcs:
        bucket: GCS-BACKUP-BUCKET-NAME-HERE
        credentialsSecret: gcp-cs-secret
```

Apply the configuration:

kubectl apply -f deploy/cr.yaml -n <namespace>

Last update: August 3, 2026
Created: August 3, 2026