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 application cluster (also referred to as a shoot or standalone Kubernetes 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

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.

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

Immutable Azure Blob Storage permissions​

If the target Azure Blob Storage container has immutable (object lock) storage enabled, the Storage Blob Data Contributor role alone is not sufficient. In addition to the base Portworx permissions provided by the portworx-wli-role custom Azure role (which grants Stork the minimum Portworx Enterprise Workload Identity permissions for Azure disks, VMs, and node pools), you must create and assign another custom role (for example, portworx-backup-locked-role) to the Managed Identity with the following permissions. For the authoritative list of required permissions and setup instructions for portworx-wli-role, see Configure authentication in the Portworx Enterprise documentation.

  • 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

  • Immutability policy permission (required to read the object-lock policy through the Azure Resource Manager API)

    • Microsoft.Storage/storageAccounts/blobServices/containers/immutabilityPolicies/read
caution

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. Assign this permission before configuring an immutable backup location.

When you add an immutable backup location, you must also provide the Resource Group Name and Subscription ID fields (described in Add a backup location), so that Stork can read the immutability policy and retention period through the Azure Resource Manager (ARM) API.

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 NameConditionalThe 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.
    Encryption KeyNoA custom encryption key to encrypt backup data at rest. If left empty, the storage account's default encryption is used.
    Subscription IDConditionalThe 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.
    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. See the note that follows this table for behavior and prerequisites.
    Assign ClustersNoEnable 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.

  6. Click Connect.

    The backup location is added in Portworx Backup. It does not become usable until it is validated — after it is created, confirm that each assigned cluster can reach it. See Validate cluster connectivity to a backup location.

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.

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.

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, or run kubectl get backuplocation <name> -n <pxb-namespace> -o yaml and check the status: 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 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
In this topic: