Skip to main content
Version: 3.1

Add an immutable GCS backup location

Applicable to Classic mode only

note

This section applies to Classic mode. For information on adding a Google Cloud Storage (GCS) immutable backup location in Federated mode, see Add a backup location.

You can add a GCS bucket with a retention policy enabled as an immutable backup location. The immutability support in GCS ensures that the backup data is protected from modification or deletion for a specified retention period through Write-Once-Read-Many (WORM) protection.

GCS enforces immutability through a bucket-level retention policy, which prevents all objects in the bucket from being deleted or overwritten until they reach the specified retention age. Portworx Backup auto-detects the retention policy on the GCS bucket and applies it to backup data stored in the bucket.

For more information on GCS retention policies, see Retention policies and Bucket Lock.

What is supported​

  • Time-based bucket-level retention policy (minimum 7 days)
  • Locked bucket-level retention policy configurations
  • Immutability for KDMP, CSI, and Portworx cloud snapshot backups
  • Auto-detection of the retention policy on GCS buckets during backup location validation
  • Scheduled backups with locked schedule policies
  • Denial of delete operations on backups stored in the GCS immutable location until their retention period expires
  • GCS lifecycle management policy integration for expired object version cleanup

What is not supported​

  • Per-object (object-level) retention holds. Only bucket-level retention policies are supported
  • Legal hold-based (event-based) immutability
  • Reducing or removing the retention period on already-locked policy buckets
  • Cross-cloud backups to GCS immutable backup locations. A cross-cloud backup is one where the application cluster runs on one cloud provider and the backup location resides on a different cloud provider — for example, backing up workloads on AWS or Azure to a GCS immutable bucket.
  • Creating GCS buckets with retention policies directly from the Portworx Backup interface

Before you begin​

Review the following Google Cloud documentation before configuring your GCS bucket:

  1. Retention policies and Bucket Lock
  2. Create and manage retention policies
  3. Object Lifecycle Management
  4. Create storage buckets

GCS console prerequisites​

Before adding the GCS immutable backup location in Portworx Backup, complete the following steps in the GCS console:

Create or configure a GCS bucket with a retention policy​

GCS immutability is implemented through a bucket-level retention policy. You can configure a retention policy on a new bucket or on an existing bucket.

  1. In the GCS console, create a new bucket or open an existing bucket.

  2. Enable Object versioning on the bucket. Portworx Backup requires object versioning to be enabled alongside the retention policy.

  3. Set a retention policy on the bucket. The retention policy defines the minimum duration that objects must be retained before they can be deleted or overwritten.

    note

    Portworx Backup requires a minimum retention period of 7 days (protection period + incremental backup count + 1 day buffer). Ensure the bucket retention period is 7 days or greater.

  4. Lock the retention policy. Locking a retention policy makes it permanent and irreversible. A locked policy cannot be removed or shortened, and can only be extended. A locked bucket is required for an immutable GCS backup location.

    important

    Locking a retention policy is irreversible. Once locked, you cannot reduce or remove the retention period.

  5. Enable Uniform bucket-level access on the bucket. GCS requires uniform bucket-level access when a retention policy is configured.

Configure a lifecycle management policy​

Configure a lifecycle management policy on the GCS bucket to automatically delete expired object versions and delete markers. Without lifecycle management, expired object versions may accumulate and increase storage costs.

  1. In the GCS console, navigate to your bucket and select the Lifecycle tab.
  2. Add a rule to delete objects after their retention period expires.

For more information, see Object Lifecycle Management.

Add a GCS immutable backup location​

Prerequisites​

  • Portworx Backup 3.1.0 or later with Stork 26.4.0 or later (and Portworx Enterprise 3.6.2 or later on Kubernetes 1.33 or later). GCS immutable backup location support was introduced in Portworx Backup 3.1.0. For the full compatibility details, see the Feature Support Matrix.
  • A GCP cloud credential must be created in Portworx Backup before adding the backup location.
  • The GCS locked bucket must already exist. Portworx Backup does not create GCS locked buckets. The bucket can be in any GCS location (region) and storage class.
  • The service account associated with the GCP cloud credential must have permissions to list, read, write, and delete objects on the target bucket, plus storage.buckets.get to read the bucket's retention policy. The Storage Object Admin (roles/storage.objectAdmin) role grants the object permissions but does not include storage.buckets.get; grant storage.buckets.get separately (for example, through roles/storage.legacyBucketReader) or use a custom role that includes both the object permissions and storage.buckets.get.
  • A GCS bucket with object versioning and a locked retention policy configured (minimum 7 days). See GCS console prerequisites.

Procedure​

To add a GCS immutable backup location in Portworx Backup, follow these steps:

  1. Log in to the Portworx Backup UI.
  2. From the left navigation pane, click the Cloud Settings icon and select the Backup Locations tab.
  3. Click Add Backup Location.
  4. On the Add Backup Location page, select the Object Store option and specify the following information:

    • Name: Enter a name for the backup location. Portworx Backup displays this name in the web console.

    • Cloud Account: Select the GCP cloud credential this backup location should use.

    • Path / Bucket: Enter the name of the GCS bucket with a retention policy configured. Enter only the bucket name (for example, my-immutable-bucket). Do not include path prefixes, slash characters, or a gs:// URI.

      note

      Portworx Backup auto-detects the bucket-level retention policy during validation. Backups cannot be physically deleted until the retention period expires, and storage usage may increase due to retained object versions. Ensure that the schedule policy retention period aligns with the bucket's retention policy to avoid over-retention or delete failures.

    • Encryption key (Optional): Enter the optional encryption key to encrypt your backup data at rest. For more information, see Encryption matrix.

  5. Click Add.

Portworx Backup validates the configuration and adds the backup location. The GCS immutable backup location appears in the Backup Locations list with a lock icon, indicating that the retention policy is active.

If the configuration is invalid, the web console displays an error indicating that the backup location could not be added.

Manage GCS immutable backup location​

After adding a GCS immutable backup location, you can perform the following actions on the backup location from the Backup Locations tab:

  • View JSON: View metadata and detailed information about the backup location.
  • Remove: Delete the backup location from Portworx Backup.
  • Edit: Modify the cloud account associated with the backup location.
  • Validate: Re-validate the backup location after it is added.
  • User Access: Set backup location access to public (available to all Portworx Backup users) or restrict to a specific user or group.
note

Backups stored in a GCS bucket with a retention policy cannot be deleted until the retention period expires. Portworx Backup enforces this check and returns an error if you attempt to delete a backup before its retention period has elapsed.

Last updated on
In this topic: