Skip to main content
Version: 3.1

Configure Backup Location (Federated Mode)

Applicable to Federated mode only

In Federated mode (also referred to as Managed Service Provider mode or Workload Identity mode), cloud credentials are not stored on the Portworx Backup server. Instead, Stork on each shoot cluster authenticates directly with the backup location using cloud-native Workload Identity mechanisms:

  • Azure: Azure Managed Identity authenticates Stork with Azure Blob Storage.
  • AWS: AWS IRSA (IAM Roles for Service Accounts) authenticates Stork with AWS S3.
  • GCP: GCP Workload Identity Federation authenticates Stork with Google Cloud Storage (GCS), including GCS buckets with a retention policy (immutability) enabled.

This enables a secretless architecture, where no cloud credentials are stored on the Portworx Backup server.

note

Throughout this article, application cluster refers to the Kubernetes cluster that runs your workloads and Stork, and where backup operations are performed. In Gardener environments, an application cluster is also called a shoot cluster; a non-Gardener application cluster is sometimes called a standalone cluster.

Supported backup locations​

The following backup location types are supported in Federated mode:

Backup locationWorkload Identity mechanismSupported since
Azure Blob StorageAzure Managed IdentityPortworx Backup 3.0.0
AWS S3AWS IRSA (IAM Roles for Service Accounts)Portworx Backup 3.1.0
Google Cloud Storage (GCS)GCP Workload Identity FederationPortworx Backup 3.1.0

Starting from Portworx Backup 3.1.0, Google Cloud Storage (GCS) buckets with a retention policy (immutability) enabled are also supported through GCP Workload Identity.

Prerequisites​

Before configuring backup locations in Federated mode, ensure that the following prerequisites are met. For hardware, storage, and network requirements for the backup cluster, see Deployment requirements in the Federated Mode Specifications.

Portworx Backup RBAC: To add, edit, share, or delete a backup location, your Portworx Backup user must have a role with backup location management permissions — the Super Administrator (px-backup-super.admin) or Infrastructure Administrator (px-backup-infra.admin) role. The Application User (px-backup-app.user) role can only view backup locations shared with it. This Portworx Backup-side RBAC is separate from the cloud-side identity permissions described below. For the full privilege breakdown, see the Role Matrix.

Common prerequisites (all providers): Stork is deployed through the Portworx Operator as part of a Portworx Enterprise installation on each application cluster (Gardener shoot or standalone shoot cluster). Standalone Stork deployments are not supported in Federated mode. The minimum versions of Portworx Backup, Portworx Enterprise, Stork, and the Portworx Operator depend on the backup location provider:

ProviderPortworx BackupPortworx EnterpriseStorkPortworx Operator
Azure Blob Storage3.0.0 or later3.6.1 or later26.3.0 or later26.2.0 or later
AWS S33.1.0 or later3.6.2 or later26.4.0 or later26.3.0 or later
Google Cloud Storage (GCS, including retention policy enabled)3.1.0 or later3.6.2 or later26.4.0 or later26.3.0 or later

Review the provider-specific prerequisites below.

Azure-specific prerequisites:

  • Portworx Backup is installed in Federated mode at the version listed above. See Install in Federated Mode.

  • Portworx Enterprise 3.6.1 or later, Stork 26.3.0 or later, and Portworx Operator 26.2.0 or later are installed on each application cluster.

  • An Azure Managed Identity is provisioned and bound to the Stork service account on each shoot cluster, with the role required for your storage type:

    • Standard (non-immutable) Azure Blob Storage: the Storage Blob Data Contributor role on the target container.

    • Immutable (object lock-enabled) Azure Blob Storage: the Storage Blob Data Contributor role alone is not sufficient. Assign a custom role (for example, portworx-backup-locked-role) with the following permissions:

      • Storage account permissions
        • Microsoft.Storage/storageAccounts/read
      • Container permissions
        • Microsoft.Storage/storageAccounts/blobServices/containers/read
        • Microsoft.Storage/storageAccounts/blobServices/containers/write
        • Microsoft.Storage/storageAccounts/blobServices/containers/delete
      • Blob permissions
        • Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read
        • Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write
        • Microsoft.Storage/storageAccounts/blobServices/containers/blobs/delete
        • Microsoft.Storage/storageAccounts/blobServices/containers/blobs/move/action
        • Microsoft.Storage/storageAccounts/blobServices/containers/blobs/add/action
      • User delegation key permission (required for immutable containers)
        • Microsoft.Storage/storageAccounts/blobServices/generateUserDelegationKey/action

      The generateUserDelegationKey/action permission is mandatory for immutable Azure Blob Storage. Without it, Stork cannot generate user delegation keys and backup operations to immutable containers fail.

      The Managed Identity must also have the base Portworx Enterprise Workload Identity permissions (typically assigned via the portworx-wli-role), which grant access to Azure compute resources such as disks, VMs, and node pools. For the complete list, see Prepare your AKS Cluster in the Portworx Enterprise documentation.

      You must also provide the Resource Group Name and Subscription ID when you add the backup location (see the field table in Add a backup location) so that Stork can validate the immutability policy and retention period through Azure Resource Manager (ARM).

    note

    The Owner role on the Azure Storage account does not grant access to blob data. You must explicitly assign the appropriate role for your storage type (Storage Blob Data Contributor for standard storage, or the custom role for immutable storage). Without this, Stork cannot read or write backup data even if the identity has Owner-level access.

    For verification steps, see Verify Stork configuration on each application cluster in the installation guide.

  • The Azure Blob Storage container exists and is accessible from the shoot cluster network.

AWS-specific prerequisites:

  • Portworx Enterprise 3.6.2 or later, Stork 26.4.0 or later, and Portworx Operator 26.3.0 or later are installed on each application cluster.

  • AWS IAM Roles for Service Accounts (IRSA) is configured on each application cluster (Gardener AWS shoot cluster). This requires an OIDC identity provider associated with the cluster. For setup guidance, see IAM roles for service accounts in the AWS documentation.

  • An IAM role is created and associated with the Stork Kubernetes service account on each shoot cluster through IRSA. The IAM role must grant the following permissions on the target S3 bucket. These permissions are scoped by resource level — some apply at the account level, some at the bucket level, and some at the object level:

    Account-level (Resource "*") — ListAllMyBuckets is an account-level action and cannot be scoped to a single bucket:

    • s3:ListAllMyBuckets

    Bucket-level (Resource arn:aws:s3:::YOUR-BUCKET-NAME):

    • s3:CreateBucket
    • s3:ListBucket
    • s3:GetBucketLocation
    • s3:GetBucketVersioning
    • s3:PutBucketVersioning
    • s3:GetBucketObjectLockConfiguration

    Object-level (Resource arn:aws:s3:::YOUR-BUCKET-NAME/*):

    • s3:GetObject
    • s3:PutObject
    • s3:DeleteObject
    • s3:ListMultipartUploadParts
    • s3:AbortMultipartUpload

    Additional permissions for object lock-enabled (immutable) S3 buckets. If the target S3 bucket has object lock enabled, grant the following permissions in addition to those above:

    • Bucket-level (Resource arn:aws:s3:::YOUR-BUCKET-NAME):
      • s3:PutBucketObjectLockConfiguration
    • Object-level (Resource arn:aws:s3:::YOUR-BUCKET-NAME/*):
      • s3:GetObjectRetention
      • s3:PutObjectRetention
      • s3:GetObjectLegalHold
      • s3:PutObjectLegalHold
      • s3:BypassGovernanceRetention

    The following example IAM policy grants these permissions with the statements split by scope. Replace YOUR-BUCKET-NAME with the name of your S3 bucket. Omit the object-lock statement if the bucket does not have object lock enabled:

    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Sid": "AccountLevel",
          "Effect": "Allow",
          "Action": [
            "s3:ListAllMyBuckets"
          ],
          "Resource": "*"
        },
        {
          "Sid": "BucketLevel",
          "Effect": "Allow",
          "Action": [
            "s3:CreateBucket",
            "s3:ListBucket",
            "s3:GetBucketLocation",
            "s3:GetBucketVersioning",
            "s3:PutBucketVersioning",
            "s3:GetBucketObjectLockConfiguration"
          ],
          "Resource": "arn:aws:s3:::YOUR-BUCKET-NAME"
        },
        {
          "Sid": "ObjectLevel",
          "Effect": "Allow",
          "Action": [
            "s3:GetObject",
            "s3:PutObject",
            "s3:DeleteObject",
            "s3:ListMultipartUploadParts",
            "s3:AbortMultipartUpload"
          ],
          "Resource": "arn:aws:s3:::YOUR-BUCKET-NAME/*"
        },
        {
          "Sid": "ObjectLockEnabledBuckets",
          "Effect": "Allow",
          "Action": [
            "s3:PutBucketObjectLockConfiguration",
            "s3:GetObjectRetention",
            "s3:PutObjectRetention",
            "s3:GetObjectLegalHold",
            "s3:PutObjectLegalHold",
            "s3:BypassGovernanceRetention"
          ],
          "Resource": [
            "arn:aws:s3:::YOUR-BUCKET-NAME",
            "arn:aws:s3:::YOUR-BUCKET-NAME/*"
          ]
        }
      ]
    }

  • The IAM role must include a trust relationship that allows the cluster OIDC provider to assume it on behalf of the Stork service account. The trust policy sub condition must target the stork service account in the namespace where Portworx is installed. Use the following trust policy, replacing <aws-account-id>, <oidc-provider-url> (the OIDC provider URL for your cluster, without the https:// prefix), and <portworx-installed-namespace>:

    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Principal": {
            "Federated": "arn:aws:iam::<aws-account-id>:oidc-provider/<oidc-provider-url>"
          },
          "Action": "sts:AssumeRoleWithWebIdentity",
          "Condition": {
            "StringEquals": {
              "<oidc-provider-url>:aud": "sts.amazonaws.com",
              "<oidc-provider-url>:sub": "system:serviceaccount:<portworx-installed-namespace>:stork"
            }
          }
        }
      ]
    }

    For verification steps, see Verify Stork configuration on each application cluster in the installation guide.

  • The target AWS S3 bucket already exists and is accessible from the shoot cluster network. Backup location validation requires the bucket to be present. The s3:CreateBucket permission listed above is needed only if you want Portworx Backup to create the bucket automatically when it does not already exist; if you pre-create the bucket (the typical case), you can omit s3:CreateBucket from the IAM role.

GCP-specific prerequisites:

  • Portworx Enterprise 3.6.2 or later, Stork 26.4.0 or later, and Portworx Operator 26.3.0 or later are installed on each application cluster.

  • GCP Workload Identity Federation is configured on each application cluster (Gardener GCP shoot cluster).

  • A GCP service account is created and mapped to the Stork Kubernetes service account on each shoot cluster through GCP Workload Identity Federation (a Workload Identity Pool and OIDC provider bound to the Gardener shoot cluster's OIDC issuer). GKE-native Workload Identity is not supported, because Portworx pods run with hostNetwork: true, which bypasses the GKE metadata server. For guidance on creating the service account, see Create service accounts, and for the federation mechanism, see Workload Identity Federation in the Google Cloud documentation. The GCP service account must have the following permissions on the target GCS bucket:

    • storage.buckets.get
    • storage.buckets.create
    • storage.objects.list
    • storage.objects.get
    • storage.objects.create
    • storage.objects.delete

    The object-level permissions (storage.objects.*) are granted by the predefined IAM role roles/storage.objectAdmin. Bucket-level permissions (storage.buckets.get and storage.buckets.create) are included in roles/storage.admin. You may use these predefined roles or a custom role with the equivalent permissions. Note that roles/storage.objectAdmin grants the storage.objects.* permissions but does not include storage.buckets.get; if you do not use roles/storage.admin, grant storage.buckets.get separately (for example, through roles/storage.legacyBucketReader) or use a custom role that includes all the permissions listed above.

    The GCP service account must also have the base Portworx Enterprise Workload Identity permissions required for compute resources on the shoot cluster. For details, see the Prerequisites in Manage Clusters (Federated Mode).

    For verification steps, see Verify Stork configuration on each application cluster.

  • The GCP Workload Identity Federation credential configuration must be supplied to Stork through a ConfigMap referenced in the StorageCluster (STC) spec at spec.workloadIdentity.gcp.credentialsConfigMap, together with spec.stork.useWorkloadIdentity: true. The Portworx Operator uses this ConfigMap to mount the credential configuration and set the GOOGLE_APPLICATION_CREDENTIALS environment variable on the Stork pods. This ConfigMap must be present; without it, Stork cannot authenticate to GCS and backup location operations fail. For the STC configuration and verification, see Verify Stork configuration on each application cluster.

  • Immutable (retention policy-enabled) GCS: GCS enforces immutability through a bucket-level retention policy, rather than per-object locks. To use an immutable GCS bucket as a Federated mode backup location, configure the target bucket as follows:

    • Enable Object versioning on the bucket.
    • Configure a retention policy on the bucket with a minimum retention period of 7 days. Lock the retention policy if your compliance requirements mandate permanent, irreversible retention — a locked policy cannot be shortened or removed, only extended.
    • Enable Uniform bucket-level access on the bucket, which GCS requires when a retention policy is configured.
    • Configure a lifecycle management policy to delete expired object versions and avoid unbounded storage growth.

    The storage.buckets.get permission listed above lets Stork read the bucket's retention policy during backup location validation. No additional GCP permissions are required for immutability. For the detailed console steps to configure a retention policy and Bucket Lock on a GCS bucket, see Retention policies and Bucket Lock in the Google Cloud documentation.

  • The target GCS bucket already exists and is accessible from the shoot cluster network. Backup location validation requires the bucket to be present. The storage.buckets.create permission listed above is needed only if you want Portworx Backup to create the bucket automatically when it does not already exist; if you pre-create the bucket (the typical case), you can omit storage.buckets.create.

Add a backup location​

Federated mode supports Azure Blob Storage, AWS S3, and Google Cloud Storage (GCS) backup locations. The procedure is the same for all providers; only the service provider selection and a few provider-specific fields differ.

note

AWS S3 and Google Cloud Storage (GCS) are supported as backup locations in Federated mode starting from Portworx Backup 3.1.0. Configure AWS IRSA (for AWS S3) or GCP Workload Identity Federation (for GCS) on the application cluster before adding the backup location.

To add a backup location in Federated mode, follow these steps:

  1. Log in to the Portworx Backup web console.

  2. From the left navigation pane, click Locations.

  3. Click Add backup location.

  4. In the Create Backup Location page, select the service provider in the Select Service Provider drop-down menu:

    • For an Azure Blob Storage backup location, select Azure.
    • For an AWS S3 backup location, select AWS.
    • For a Google Cloud Storage (GCS) backup location (including a GCS immutable bucket with a bucket-level retention policy), select Google Cloud.

  5. Specify the following information. The Applies to column indicates whether a field is common to all providers or specific to one:

    FieldApplies toMandatoryDescription
    NameAll providersYesA descriptive name for this backup location.
    Azure Storage Account NameAzureYesThe name of the Azure Storage account that hosts the backup container.
    Path/BucketAll providersYesThe name of the target storage container or bucket. For Azure, enter the Blob Storage container name. For AWS, enter the S3 bucket name. For GCS, enter the bucket name (for an immutable GCS bucket, enter the name of the bucket with a retention policy configured). Enter only the container or bucket name. Do not include path prefixes or slash characters.
    Azure EnvironmentAzureYesThe Azure cloud environment.
    The default value is set to Azure Global.
    Select Azure Global or Azure China if applicable.
    RegionsAWS S3YesThe AWS region where the S3 bucket is located (for example, us-east-1).
    Project IDGCSYesThe ID of the GCP project that owns the GCS bucket.
    Resource Group NameAzureConditionalThe Azure resource group that contains the storage account. Required if the Azure Blob Storage container has immutable object lock enabled; otherwise optional. Stork uses this value to read the immutability policy and retention period via Azure Resource Manager (ARM). Without it, backup location validation fails for object-lock-enabled containers.
    Subscription IDAzureConditionalThe Azure subscription ID associated with the storage account. Required if the Azure Blob Storage container has immutable object lock enabled; otherwise optional. Stork uses this value together with the Resource Group Name to access the Azure Resource Manager (ARM) API for immutability policy validation.
    Encryption KeyAll providersNoA custom passphrase used to encrypt backup data at rest. If left empty, the default encryption setting of the storage account or bucket is used. Store this key securely. It cannot be changed after the backup location is created and is not recoverable from Portworx Backup. If it is lost, backups encrypted with it cannot be decrypted or restored.
    Storage ClassAWS S3NoThe S3 storage class to use for backup objects. For more information on supported storage class types, see S3 storage classes.
    Server-side encryption (SSE-S3)AWS S3NoSelect this option to encrypt backup data at the destination using AWS S3 server-side encryption. For more information, see Server-side encryption matrix.
    Sync pre-existing backups from backup locationAll providersNoSelect this checkbox to import backups already present in the backup location that were not created by this Portworx Backup instance. See the note that follows this table for behavior and prerequisites.
    Assign ClustersAll providersNoEnable this option to select and assign application clusters to this backup location after it is created.
    About syncing pre-existing backups

    Backups may be created, deleted, or modified outside the current cluster or session, causing metadata in Portworx Backup to become out of sync. When you select Sync pre-existing backups from backup location, the system refreshes the backup location and fetches the latest metadata to display the most up-to-date backups.

    The initial sync is triggered when you both select this checkbox and assign at least one cluster to the backup location during creation. Subsequent syncs are not periodic — you must trigger them manually from the Portworx Backup UI, CLI, or API. Stork on each cluster performs the sync using Workload Identity. For more information, see Synchronize backups from a backup location.

    note

    In Federated mode, no Cloud Account or stored credentials are required. Stork authenticates directly with the backup location using Workload Identity:

    • For Azure, Stork uses the Azure Managed Identity bound to the Stork service account to authenticate with the Azure Blob Storage container.
    • For AWS, Stork uses the IRSA-provided credentials to authenticate with the S3 bucket.
    • For GCP, Stork uses Application Default Credentials (ADC) provided by GCP Workload Identity Federation to authenticate with the GCS bucket.

  6. Click Connect.

    The backup location is added in Portworx Backup. For a GCS immutable backup location, the entry appears in the Locations list with a lock icon, indicating that the retention policy is active. During validation, Stork on each assigned cluster verifies connectivity to the backup location using Workload Identity and reports the validation status in the backup location details:

    • For an Azure Blob Storage backup location, Stork checks that the container exists and that the Azure Managed Identity bound to the Stork service account has the required Storage Blob Data Contributor role. For object-lock-enabled containers, it also verifies that it can read the immutability policy and retention period via Azure Resource Manager (ARM), using the Resource Group Name and Subscription ID.
    • For an AWS S3 backup location, Stork checks that the bucket exists and that the IAM role associated with the Stork service account has the required permissions.
    • For a Google Cloud Storage (GCS) backup location, Stork checks that the bucket exists and that the GCP service account bound to the Stork Kubernetes service account has the required permissions (storage.buckets.get, storage.objects.list, storage.objects.create).

    Validation states​

    After you click Connect, the backup location moves through the following validation states, which are reported in the backup location details:

    • Validating — Validation is in progress. Stork on each assigned cluster is attempting to reach the bucket or container and verify its permissions.
    • Success (also shown as Validated) — Connectivity and permissions are confirmed. Stork can reach the bucket or container, and the Workload Identity (Azure Managed Identity, AWS IRSA, or GCP Workload Identity Federation) has the required role or permissions.
    • Failed — Stork could not connect to the bucket or container, or the Workload Identity binding (Azure Managed Identity, AWS IRSA, or GCP service account) or its permissions are insufficient. The status includes the reason.

    Troubleshooting validation, sync, and delete failures​

    If validation, sync, or delete operations fail, the cause is usually on the application cluster, because Stork (not the Portworx Backup server) accesses the backup location. Common causes include:

    • Workload Identity not bound to the Stork service account. The Azure Managed Identity, AWS IAM role, or GCP service account is not associated with the stork service account. For AWS, the IRSA trust policy sub condition must match system:serviceaccount:<portworx-installed-namespace>:stork. For GCP, the Stork Kubernetes service account must be mapped to the GCP service account through Workload Identity Federation, and the credential configuration ConfigMap referenced in the STC spec (spec.workloadIdentity.gcp.credentialsConfigMap) must be present so the Operator can set GOOGLE_APPLICATION_CREDENTIALS on the Stork pods.
    • Missing or incorrect permissions. For Azure, the Managed Identity is missing the Storage Blob Data Contributor role (or the custom role required for immutable containers). For AWS, the IAM role is missing a required permission, or a permission is scoped to the wrong resource level (account, bucket, or object). For GCP, the service account is missing a required permission on the target bucket (storage.buckets.get, storage.objects.list, storage.objects.get, storage.objects.create, storage.objects.delete). See the provider-specific prerequisites.
    • No network access to the storage endpoint. The cluster network cannot reach the Azure Blob Storage, AWS S3, or Google Cloud Storage endpoint for the target container or bucket.
    • Object-lock or immutability retention blocking deletes. If the bucket or container has object lock, immutability, or retention enabled, retention or legal hold can prevent deletion of objects until the retention period expires. This is expected behavior, not a misconfiguration.

    To diagnose a failure:

    • Check the backup location status and the per-cluster reason reported in the backup location details or on the Clusters Info page.

    • Check the Stork logs on the affected cluster:

      kubectl logs -n <portworx-installed-namespace> -l name=stork

    • Re-verify the Stork configuration on the cluster. See Verify Stork configuration on each application cluster.

View backup location JSON​

To view the raw JSON definition of a backup location, follow these steps:

  1. Log in to the Portworx Backup web console.
  2. From the left navigation pane, click Locations.
  3. Locate the backup location and click the options menu (⋮) in its row.
  4. Select View JSON.

The JSON view shows the full backup location object as stored in Portworx Backup, including metadata, status, and configuration fields.

Edit a backup location​

To edit an existing backup location, follow these steps:

  1. Log in to the Portworx Backup web console.

  2. From the left navigation pane, click Locations.

  3. Locate the backup location and click the options menu (⋮) in its row.

  4. Select Edit.

  5. In the Edit Backup Location page, update the cluster assignment:

    note

    The only editable field in the Edit Backup Location page is Assign Clusters. All other backup location fields — such as name, storage account, path/bucket, environment, and encryption settings — cannot be modified after the backup location is created.

    Enable the Assign Clusters option to add or change the application clusters assigned to this backup location.

  6. Click Connect.

Validate cluster connectivity to a backup location​

Use the Validate Clusters option to check whether all clusters associated with a backup location can successfully connect to it. This is useful after network changes, credential updates, or when you want to confirm that Stork on each cluster can reach the backup location independently.

To validate cluster connectivity to the backup location, follow these steps:

  1. Log in to the Portworx Backup web console.

  2. From the left navigation pane, click Locations.

  3. Select the target backup location and click the options menu (⋮) in its row.

  4. Click Validate Clusters. The system displays the Clusters Info page that lists all the clusters associated with the backup location.

  5. Select the associated clusters, and click Validate Sync.

    Stork on each selected cluster independently attempts to reach the backup location using Workload Identity, and the result is reported per cluster on the Clusters Info page:

    • Success — the cluster can reach the backup location and the Workload Identity bound to Stork (Azure Managed Identity, AWS IRSA, or GCP service account) has the required permissions.
    • Failed — the cluster cannot connect. The reported reason indicates the cause, such as missing permissions, an inaccessible bucket or container, or a network error.

    If validation fails for a cluster, verify the following on that cluster, then run the validation again:

    • Workload Identity is correctly configured for Stork (Azure Managed Identity, AWS IRSA, or GCP service account binding to the stork service account). For verification steps, see Verify Stork configuration on each application cluster.
    • The identity has the required permissions on the target bucket or container (see Prerequisites).
    • The bucket or container exists and is reachable from the cluster network.

Synchronize backups from a backup location​

Use Sync Backups to manually discover and register backup objects from the backup location in Portworx Backup.

note

Backups may be created, deleted, or modified outside the current cluster or session, causing metadata in Portworx Backup to become out of sync. You can select the Sync pre-existing backups from backup location checkbox while adding the backup location to refresh the backup location and fetch the latest metadata to display the most up-to-date backups. Backup sync is initiated when you select this checkbox and assign at least one cluster to the backup location during backup location creation. For more information, see Add a backup location. The initial sync occurs after this configuration. Subsequent sync operations are not periodic and must be triggered manually using the Portworx Backup UI, CLI, or API.

In Federated mode, the Portworx Backup server does not store backup location credentials, so it cannot automatically scan the backup location. As a result, backups created, deleted, or changed outside the current Portworx Backup instance, such as from another cluster or a previous setup, may not appear automatically.

Instead, Stork on each application cluster accesses the backup location directly using Workload Identity.

When you run Sync Backups, Portworx Backup instructs Stork to discover backups and update the list. This ensures that the latest backup metadata is retrieved and displayed in Portworx Backup.

To synchronize backups from the backup location, follow these steps:

  1. Log in to the Portworx Backup web console.
  2. From the left navigation pane, click Locations.
  3. Select the target backup location and click the options menu (⋮) in its row.
  4. Click Sync Backups.

The All Backups page is updated to reflect the current state of the backup location, including backups created, deleted, or modified outside the current Portworx Backup instance.

note

If multiple backup locations point to the same storage bucket or container (Azure Blob Storage, AWS S3, or GCS), only one Sync Backups operation can run at a time. Additional sync attempts for the same bucket fail while a sync is in progress.

To check whether a sync is already running before retrying, view the backup location's JSON (see View backup location JSON) and inspect its sync status field: a value of Pending or InProgress indicates an active sync. Wait until the status returns to a completed or idle state, then retry.

When the blocked sync is triggered by a different user operating a different backup location on the same bucket, that user cannot tell from the UI alone which backup location holds the active sync or when it will complete. As a workaround, when multiple users manage backup locations that share the same bucket, an administrator should coordinate sync operations so that they run sequentially and do not conflict.

Share a backup location​

You can share a backup location with other users or groups in your organization so they can use it when configuring clusters or backup policies.

To share a backup location, follow these steps:

  1. Log in to the Portworx Backup web console.
  2. From the left navigation pane, click Locations.
  3. Locate the backup location and click the options menu (⋮) in its row.
  4. Select Share.
  5. In the Share <Backup Location> page, search for and add the users or groups to share with, and set their access level (View or Edit).
  6. Click Share.

Sharing grants access but does not transfer ownership. The backup location remains owned by the user who created it.

With View access, you can see and use the backup location when configuring clusters or backup policies.
With Edit access, you can also modify backup location settings but cannot delete the backup location or change its ownership.

Delete a backup location​

Deletion is governed by two independent sets of rules — one enforced by the web console and one enforced by the API:

  • Web console (UI) check — cluster assignment. If the backup location is currently assigned to one or more clusters, the web console requires you to reassign those clusters to an alternate backup location before deleting. This check is enforced by the UI only; deleting directly through the API bypasses it.
  • API-side blocks — active references and in-progress sync. Regardless of how you trigger the deletion, the API blocks it when the backup location has active Backup, Schedule, or Restore references, or when a sync operation is in the Pending or InProgress state.

To delete a backup location, follow these steps:

  1. Log in to the Portworx Backup web console.

  2. From the left navigation pane, click Locations.

  3. Locate the backup location and click the options menu (⋮) in its row.

  4. Select Remove.

  5. Select the acknowledgment checkbox, and click Delete.

    When you delete a backup location, it transitions to a DeletePending state while Portworx Backup removes the associated metadata in the background. This process may take some time depending on the amount of metadata to be cleaned up. The backup location is fully removed once this process completes.

important

Deleting a backup location removes only the metadata and access configuration from Portworx Backup. It does not delete the backup data stored in the underlying storage bucket or container (Azure Blob Storage, AWS S3, or GCS). You must manually delete the backup data from the storage location if required.

Troubleshooting​

Because Stork on each application cluster (not the Portworx Backup server) accesses the backup location in Federated mode, most failures are diagnosed on the cluster. Use the following table to map common symptoms to their cause and resolution:

SymptomLikely causeResolution
Backup location validation fails for a clusterWorkload Identity is misconfigured, the identity lacks the required permissions, or the bucket/container is unreachable from the clusterReview the per-cluster reason on the Clusters Info page and follow Validate cluster connectivity to a backup location. For AWS, see also Troubleshooting validation, sync, and delete failures. Confirm the Stork configuration using Verify Stork configuration on each application cluster.
Sync Backups fails or does not completeAnother sync is already running against the same bucket or containerOnly one sync can run per bucket at a time. Wait for the active sync to finish and retry. When multiple users share a bucket, coordinate syncs sequentially. See the note in Synchronize backups from a backup location.
Backup location cannot be deletedThe backup location has active Backup, Schedule, or Restore references, a sync is in Pending or InProgress state, clusters are still assigned, or object-lock retention on the bucket is blocking object deletionReassign or remove dependent objects and assigned clusters, wait for any in-progress sync to complete, then retry. For object-lock buckets, deletion is blocked until the retention period expires, which is expected. See Delete a backup location.

Next steps​

Perform Backup and Restore operations. For more information, see Backup and Restore.

Last updated on
In this topic: