Upgrade Portworx Backup in Federated Mode

Applicable to Federated mode only

This topic describes how to upgrade an existing Portworx Backup Federated mode deployment to 3.1.0. Portworx Backup 3.1.0 adds support for AWS S3 and Google Cloud Storage (GCS) backup locations in Federated mode, in addition to the Azure Blob Storage support introduced in 3.0.0.

If you have not yet installed Portworx Backup in Federated mode, see Install Portworx Backup in Federated Mode instead.

Supported upgrade path

Current deployment	Target version	Supported
Federated mode 3.0.0 (Azure Blob Storage)	3.1.0	Yes — in-place Helm upgrade of the backup cluster
Classic mode (any version)	Federated mode 3.1.0	No — see the note below

important

You cannot convert an existing Classic mode deployment to Federated mode by upgrading. Federated mode must be installed as a new deployment. The pre-upgrade health check blocks an in-place upgrade from Classic mode to Federated mode. This topic applies only to upgrading an existing Federated mode deployment.

What the upgrade involves

A Federated mode upgrade has two parts, performed separately:

1. Backup cluster — Upgrade the Portworx Backup server on the dedicated backup cluster using Helm. This is the main procedure on this page.
2. Application clusters — Upgrade Portworx Enterprise and Stork on each application (shoot) cluster to the minimum versions required for your backup location provider. Stork is upgraded through the Portworx Operator as part of the Portworx Enterprise installation, not through Portworx Backup. See Upgrade Stork on application clusters.

Ordering when adopting AWS S3 or GCS

The two parts are performed separately, but the order matters when you adopt a new backup location provider (AWS S3 or GCS) that you did not use before. Because the backup location type and Stork Workload Identity validations run when you add a backup location, you must upgrade Stork to 26.4.0 or later and configure the provider's Workload Identity on the application clusters before you add the AWS S3 or GCS backup location. For a deployment that continues to use only Azure Blob Storage, the backup-cluster and application-cluster upgrades have no ordering dependency.

Prerequisites

Before you upgrade the backup cluster, ensure that the following conditions are met:

• kubectl access: Your kubectl context is set to the backup cluster with administrative privileges.
• Helm version: Helm 3.x is installed on the workstation running the upgrade command.
• MongoDB pod health: All three MongoDB pods (pxc-backup-mongodb-0, pxc-backup-mongodb-1, pxc-backup-mongodb-2) are in the Ready state. The pre-upgrade health check fails the upgrade if any MongoDB pod is not ready. For recovery steps, see Pre-upgrade job.
• pxc-credentials secret: The pxc-credentials secret is present in the Portworx Backup namespace with valid database passwords. See Password Policy.
• PVC storage: Sufficient storage is available on the PVCs used by Portworx Backup components. Do not change the Namespace or StorageClass values used at initial installation — these cannot be modified during an upgrade.
• Application cluster versions: Confirm the minimum Portworx Enterprise, Stork, and Portworx Operator versions for your backup location provider. See Prerequisites in Manage Clusters (Federated Mode).
• Back up critical data and configuration: An upgrade affects the entire backup cluster, and Helm rollback is not supported for Federated mode (see the note that follows), so you cannot simply revert if something goes wrong. Before you begin, back up any critical data and save your current Helm values (for example, run helm get values px-central -n <pxb-namespace> -o yaml > values-backup.yaml) so that you can reproduce your configuration if needed.

note

Do not use the --no-hooks flag with the Helm upgrade command. It bypasses the pre-upgrade and post-upgrade hooks and can leave the deployment in an inconsistent state. If you encounter an upgrade failure, do not roll back with Helm rollback — contact the Portworx Backup support team.

Upgrade the backup cluster

You upgrade the Portworx Backup server on the backup cluster with helm upgrade, reusing the same Helm values you used at installation. The Federated mode flag (pxbackup.federated=true) must remain set during the upgrade.

Health check runs first

When you run the Helm upgrade, Portworx Backup runs a pre-upgrade health check before applying any changes. If a check fails — for example, a MongoDB pod is not ready, or the upgrade path is unsupported — the upgrade is blocked and the failures are recorded in the health check report. Review the report and resolve any issues before retrying. For details, see Health Check for Install and Upgrade and Retrieving health check results after a failed install or upgrade.

1. Generate the upgrade specs. Use the Portworx Central Spec Generator to produce the upgrade command for 3.1.0. Select Federated in the Spec Details tab so that the generated command includes pxbackup.federated=true, and keep the same Namespace and StorageClass values used at initial installation. For a walkthrough of the Spec Generator fields, see Generate installation specs using Portworx Central.

2. Update the Helm repository:

   helm repo add portworx http://charts.portworx.io/ && helm repo update

   Air-gapped environments

   The command above pulls the Helm chart from the public Portworx repository and works only where the backup cluster has internet access. In an air-gapped or restricted network, upgrade from your private registry instead: pre-load the required Portworx Backup images into your private registry and use the Use custom registry option in the Spec Generator so the generated command references your registry. This is the same air-gapped path used for a Federated mode install — see Set up the installation environment.

3. Ensure the pxc-credentials secret exists in the Portworx Backup namespace. If it does not, create it by running the secret-creation command that the Spec Generator provides on its Finish tab. The upgrade fails if this secret is missing.

4. Run the generated helm upgrade command. Reuse your existing configuration values and keep pxbackup.federated=true. Because a Federated mode upgrade involves several components, increase the Helm timeout to avoid premature failures:

   helm upgrade px-central portworx/px-central \
     --namespace <pxb-namespace> \
     --version 3.1.0 \
     --set persistentStorage.enabled=true \
     --set persistentStorage.storageClassName="<storage-class-name>" \
     --set pxbackup.enabled=true \
     --set pxbackup.federated=true \
     --timeout=120m

   About the --timeout value

   The default Helm timeout (5 minutes) is often too short for a Portworx Backup upgrade, because Helm waits for several StatefulSets, Deployments, and post-upgrade hooks to become ready. --timeout=120m is a safe upper bound, not a measured duration — most upgrades finish well before it, and Helm returns as soon as the release is ready rather than waiting the full 120 minutes. You can set a different value, but it must be long enough for all pods and hooks to complete in your environment. If the timeout is too short, Helm reports a timeout error and marks the release as failed even though the upgrade may still be progressing in the cluster.

   To retain all customizations from your previous installation (for example, image registry paths, proxy settings, or Prometheus configuration), upgrade with a values file instead of --set. Retrieve your current values and reuse them, following the same procedure documented for Classic mode in Upgrade Portworx Backup on non air-gapped environments. The only Federated-specific requirement is that pxbackup.federated: true remains set in the values file.

note

Do not change the Namespace or StorageClass during an upgrade. PVCs are created from the values defined at initial installation, and these values cannot be modified later.

Upgrade using Argo CD

If you installed Portworx Backup in Federated mode using Argo CD, upgrade it using the same GitOps workflow instead of running helm upgrade manually. Update the target chart version to 3.1.0 in your Argo CD application, keep pxbackup.federated=true and isArgoCD=true in the Helm values, and sync the application. Generate the updated 3.1.0 values from the Portworx Central Spec Generator with Federated and Argo CD selected, as described for a new install in Method 2: Install using Argo CD.

Verify the upgrade

After the Helm upgrade completes, confirm that the backup cluster is healthy:

1. Confirm that the post-upgrade hook job completed. In the kubectl get job output, the COMPLETIONS column should show 1/1:

   kubectl get job pxcentral-post-install-hook -n <pxb-namespace>

   A COMPLETIONS value of 1/1 indicates the hook finished successfully. You can also confirm that the hook pod reports the Completed phase:

   kubectl get pods -n <pxb-namespace> -l job-name=pxcentral-post-install-hook

   If the upgrade failed, see Retrieving health check results after a failed install or upgrade.

2. Confirm that all Portworx Backup pods, including the MongoDB pods, are in the Running or Completed state and that the MongoDB pods are Ready:

   kubectl get pods -n <pxb-namespace>

   Wait until every MongoDB pod (for example, pxc-backup-mongodb-0) shows 1/1 in the READY column.

3. Log in to the Portworx Backup web console and confirm that it is reachable and reports the upgraded version.

   To review or change how the console is exposed (ClusterIP versus LoadBalancer, internal load balancer annotations, or source ranges), see Configure Access to Portworx Backup Web Console.

Upgrade Stork on application clusters

Stork on each application (shoot) cluster is upgraded through the Portworx Operator as part of the Portworx Enterprise installation — not through Portworx Backup. Ensure that each application cluster meets the minimum versions for your backup location provider:

Backup location provider	Portworx Enterprise	Stork	Portworx Operator
Azure Blob Storage	3.6.1 or later	26.3.0 or later	26.2.0 or later
AWS S3	3.6.2 or later	26.4.0 or later	26.3.0 or later
Google Cloud Storage (GCS)	3.6.2 or later	26.4.0 or later	26.3.0 or later

• If you are already running Federated mode with Azure Blob Storage backup locations, your application clusters already meet the Azure minimums. No Stork change is required unless you adopt AWS S3 or GCS.
• To use AWS S3 or GCS backup locations (new in 3.1.0), upgrade Stork on each application cluster to 26.4.0 or later (through the Portworx Operator) and configure the provider's Workload Identity before adding the backup location — AWS IRSA (IAM Roles for Service Accounts) for AWS S3, or GCP Workload Identity Federation for GCS. For more information, see Prerequisites and Verify Stork configuration on each application cluster.

note

In Federated mode, Stork must be deployed through the Portworx Operator as part of a Portworx Enterprise installation. Standalone Stork deployments are not supported. Workload Identity for Stork is configured through the StorageCluster (STC) custom resource, and the Operator applies the required configuration automatically.

Next steps

• Add or validate AWS S3 or GCS backup locations. See Configure Backup Locations in Federated Mode.
• Review the Federated Mode Specifications for the current supported platforms and operations.

Related topics

• Install Portworx Backup in Federated Mode
• Manage Clusters (Federated Mode)
• Configure Backup Locations (Federated Mode)
• Upgrade Portworx Backup (Classic mode)
• Health Check for Install and Upgrade