Skip to main content
Version: 3.0

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 managed identity mechanisms, such as Azure Managed Identity. This enables a secretless architecture, where no cloud credentials are stored on the Portworx Backup server.

note

The procedures in this section use Azure Blob Storage as an example, as it is currently the only supported cloud provider in Federated mode. The general steps remain similar for other providers when they are supported.

Supported backup location​

In this release, Azure Blob Storage (object store) using Azure Managed Identity is supported as the backup location in Federated mode.

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 3.0.0 or later is installed in Federated mode. See Install in Federated Mode.

  • Stork 26.3.0 or later is running on each application cluster (shoot or standalone Kubernetes cluster), deployed through the Portworx Operator 26.2.0 or later as part of a Portworx Enterprise installation. Standalone Stork deployments are not supported in Federated mode.

  • Portworx Enterprise version 3.6.1 or later is installed on each application cluster (shoot or standalone Kubernetes cluster).

  • An Azure Managed Identity is provisioned and bound to the Stork service account on each shoot cluster, with the Storage Blob Data Contributor role on the target Azure Blob Storage container.

    note

    The Owner role on the Azure Storage account does not grant access to blob data. The Storage Blob Data Contributor role must be explicitly assigned. Without this, Stork cannot read or write backup data even if the identity has Owner-level access.

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

Add a backup location​

To add an Azure Blob 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, the Select Service Provider is automatically set to Azure, as Azure Blob Storage is the only supported backup location provider in Federated mode.

  5. Specify the following information:

    FieldMandatoryDescription
    NameYesA descriptive name for this backup location.
    Azure Storage Account NameYesThe name of the Azure Storage account that hosts the backup container.
    Path/BucketYesThe name of the Azure Blob Storage container (Bucket) to use as the backup location. Enter only the container name. Do not include any path prefixes or slash characters.
    Azure EnvironmentYesThe Azure cloud environment.
    The default value is set to Azure Global.
    Select Azure Global or Azure China if applicable.
    Resource Group NameNoThe Azure resource group that contains the storage account. Required if the Azure Blob Storage container has immutable object lock enabled. 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.
    Encryption KeyNoA custom encryption key to encrypt backup data at rest. If left empty, the storage account's default encryption is used.
    Subscription IDNoThe Azure subscription ID associated with the storage account. Required if the Azure Blob Storage container has immutable object lock enabled. Stork uses this value together with the Resource Group Name to access the Azure Resource Manager (ARM) API for immutability policy validation.
    Sync pre-existing backups from backup locationNoSelect this checkbox to import backups already present in the backup location that were not created by this Portworx Backup instance.
    Backups may be created, deleted, or modified outside the current cluster or session, causing metadata in Portworx Backup to become out of sync. If you select this checkbox, the system refreshes the backup location and fetches 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. 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. For more information, see Sync Backups. Stork on each cluster performs the sync using Workload Identity.
    Assign ClustersNoEnable this option to select and assign shoot or non-Gardener clusters to this backup location after it is created.

  6. Click Connect.

    The backup location is added in Portworx Backup.

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 shoot 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.

Synchronize backups from a backup location​

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

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 Azure Blob Storage bucket, only one Sync Backups operation can run at a time. Additional sync attempts for the same bucket fail while a sync is in progress. When the blocked sync is triggered by a different user operating a different backup location on the same bucket, that user cannot tell which backup location holds the active sync or when it will complete, and must retry manually.
As a workaround, when multiple users manage backup locations that share the same bucket, an administrator should coordinate sync operations to ensure they are performed 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​

If the backup location is currently assigned to one or more clusters, you must reassign those clusters to an alternate backup location before deleting.

note

This restriction is enforced by the web console UI only. If you delete a backup location directly through the API without first reassigning clusters, the deletion proceeds without this check. The API blocks deletion only when the backup location has active Backup, Schedule, or Restore references, or when a sync operation is in 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 Azure Blob Storage container. You must manually delete the backup data from the storage location if required.

Next steps​

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

Last updated on