Version: 3.1

Upgrade Portworx Backup Using Helm

You can upgrade Portworx Backup with default options or with advanced options based on your environment. To upgrade with default options, use Install using the 'set' command. To upgrade with advanced options, use Install using the values-px-central.yaml file. This page covers both internet-connected and air-gapped upgrades; steps and commands that differ for air-gapped environments are called out inline (for example, when downloading and referencing the Helm chart package locally instead of adding the Helm repository).

Prerequisites

Before you upgrade Portworx Backup using Helm, ensure that:

Your cluster meets the upgrade requirements. For more information, see Requirements for Upgrading Portworx Backup.
You have set up the upgrade environment.
You have generated the Portworx Backup spec and created the pxc-credentials secret. For more information, see Generate Portworx Backup Spec.

Option 1: Install using the 'set' command

To upgrade Portworx Backup with default or basic options:

Execute the following command to add the Helm repository to your cluster and update it:
```
helm repo add portworx https://charts.portworx.io/ && helm repo update
```
note
helm repo add reaches https://charts.portworx.io/ over the public internet, so it cannot run inside a true air-gapped cluster. Run this command (and the curl download used later for air-gapped upgrades) from a workstation or bastion host that has internet access, then transfer the downloaded Helm chart into your air-gapped environment. Alternatively, skip this step and use the downloaded .tgz chart directly, as described in the following steps.
Optional: If you are deploying Portworx Backup in a cluster with Istio or Linkerd as service mesh, append istio.enabled=true or linkerd.enabled=true at the end of the command provided under Install using the set command.

note
You do not have to append istio.enabled=true if you have installed Istio in ambient mode. Do not use the --no-hooks flag with the Helm upgrade command; it puts the cluster into a bad state.

Sample command:
```
helm upgrade px-central portworx/px-central --namespace central --version 3.1.0 --set persistentStorage.enabled=true,persistentStorage.storageClassName="<storage-class-name>",pxbackup.enabled=true,istio.enabled=true
```
Note that all the parameters you have provided in the Spec Details tab get appended after --set in the command.
After verifying the command for accuracy, copy and run it in the terminal to upgrade Portworx Backup. Make sure you replace the version in your command with the required version.

Option 2: Install using the values-px-central.yaml file

To upgrade Portworx Backup with advanced options:

Click values-px-central.yaml file option provided under Install using the values-px-central.yaml file on the right of Step 2. This creates and downloads a values file named values-px-central.yaml with all your configuration overrides.
Rename this as values-px-central-<pxb-release-version>.yaml. Where <pxb-release-version> is the Portworx Backup version you want to install.
Set the value for the service mesh deployed in your Portworx Backup cluster. By default, istio.enabled and linkerd.enabled are set to false. Enable only one service mesh — a pod cannot belong to both Istio and Linkerd.

note
The hostName parameter is mandatory if multiple applications use the same prefix (/) and are using the Istio sidecar mode. To avoid routing conflicts during the PX-Backup deployment, update the host name by using the istio.hostName Helm parameter. For more information, see the Configure a dedicated hostname for Portworx Backup UI with Istio section.
Do not use the --no-hooks flag with the Helm upgrade command, as it can put the cluster into a bad state.

If you use Istio (sidecar mode):
```
istio:
  enabled: true
  hostName: ""
```
If you use Linkerd:
```
linkerd:
  enabled: true
```
Save the yaml file for the changes made and validate the values.
From your CLI terminal, retrieve all custom values you used during the previous Portworx Backup installation or upgrade. These custom values are required for upgrade to retain the current configuration. Execute the following command to generate the current values YAML file:
```
helm get values --namespace <pxb-namespace> px-central -o yaml > values-current.yaml
```
Where <pxb-namespace> is the namespace in which you are planning to upgrade Portworx Backup.

This command retrieves the values used to configure the px-central Helm release and outputs them in YAML format into values-current.yaml, for review and reuse during the upgrade.
Compare the files you obtained from steps 1 and 5, and update the new values-px-central-<pxb-release-version>.yaml to carry all the customizations from the previous release.

When you initially installed Portworx Backup using Helm, you likely customized several settings (for example, image registry paths, versions, storage class names, proxy configs, and so on). During an upgrade, you must retain these customizations to avoid overwriting your working setup. Helm upgrades are declarative, and if you do not pass your previous configuration again, Helm assumes defaults.

For example: In the existing values-current.yaml, if the persistentStorage.storageClassName parameter is set with the value portworx-sc, then you must set the same portworx-sc value in the new values-px-central-<pxb-release-version>.yaml.
(Optional) Execute this step only if you have configured Prometheus following the steps mentioned in Configure Prometheus and Grafana. Delete the Prometheus operator deployment to avoid conflicts during upgrade — the Helm upgrade re-creates it:
```
kubectl delete deploy prometheus-operator -n <pxb-namespace>
```
Where <pxb-namespace> is the namespace in which you are planning to upgrade Portworx Backup.

note
This deletes only the prometheus-operator Deployment, not the Prometheus or Alertmanager instances or their data (persistent volumes are retained). The step is required because the existing operator can conflict with the operator version the Helm upgrade installs. The Helm upgrade re-creates the Deployment, so the operator returns automatically once the upgrade completes. Metrics collection is paused only briefly while the operator pod is unavailable; already-stored metrics are not lost.
(Optional) Delete the post-install hook job:
```
kubectl delete job pxcentral-post-install-hook --namespace <pxb-namespace>
```
note
If you have enabled health check, deletion of the post-install hook job is handled automatically. If not, you must delete it manually with the command above.
Run the upgrade command:
- (Internet-connected environments) Copy and execute the command under Install using the values-px-central.yaml file in your terminal:
```
helm upgrade px-central portworx/px-central --namespace <pxb-namespace> --version <pxb-release-version> -f values-px-central-<pxb-release-version>.yaml --timeout=120m
```
  During an upgrade, several components are involved, which can considerably extend the upgrade duration. Therefore, the default timeout of 5 minutes is typically inadequate, and you must increase the timeout to 120 minutes.
- (Air-gapped environments) Download the Helm chart package and reference it locally:
  1. Download the latest px-central package:
    curl -O https://raw.githubusercontent.com/portworx/helm/master/stable/px-central-<pxb-release-version>.tgz
    Where <pxb-release-version> is the Portworx Backup version you want to upgrade to.
    
    note
    This curl command downloads the Helm chart from raw.githubusercontent.com over the public internet, so it cannot run inside a true air-gapped cluster. Run it from a workstation or bastion host that has internet access, then transfer the downloaded .tgz chart into your air-gapped environment before running the helm upgrade command below.
  2. Run the upgrade using the downloaded package:
    helm upgrade px-central px-central-<pxb-release-version>.tgz --namespace <pxb-namespace> -f values-px-central-<pxb-release-version>.yaml --timeout=120m
Click Finish after you complete the upgrade installation.

To continue using the enterprise version, ensure your Portworx Backup license is still valid after the upgrade.

You can find more information about the Portworx Backup Helm chart in the helm section.

Verify the Portworx Backup upgrade

After running the upgrade command, Portworx Backup triggers a health check to evaluate whether your setup meets installation requirements. If the upgrade fails because of unmet requirements, relevant error messages are displayed in the Helm output. For more information, see health check and health check matrix.

Monitor upgrade completion

After running the Helm upgrade command, monitor the post-install hook to ensure successful deployment:

kubectl get pod --namespace <pxb-namespace> -ljob-name=pxcentral-post-install-hook -o wide | awk '{print $1, $3}' | grep -iv error

Expected output:

pxcentral-post-install-hook-xxxxx   Completed

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

Expected output:

NAME                          COMPLETIONS   DURATION   AGE
pxcentral-post-install-hook   1/1           2m         2m

Verify pod status

Ensure all Portworx Backup components, including the MongoDB pods, are running:

kubectl get pods -n <pxb-namespace>

All pods should be in Running or Completed state. Wait until every MongoDB pod (for example, pxc-backup-mongodb-0) shows 1/1 in the READY column before proceeding.

Access the Portworx Backup web console

Configure access to the Portworx Backup web console. Confirm that the deployed image tags match the target Portworx Backup version, and log in to the web console to verify it is reachable and reports the upgraded version.

note

Portworx Backup supports object lock from release version 2.2.0. For more information, see S3 Object Lock in Portworx Backup. You need the permissions listed below to check if the bucket configured in the backup location supports object lock. If you are upgrading to Portworx Backup 2.2.0 from any lower version, ensure that the following object lock related permissions are enabled in the AWS web console:

s3:GetBucketObjectLockConfiguration
s3:GetObjectLegalHold
s3:GetObjectRetention

What to do next

On each application cluster that you back up, upgrade Stork to a version compatible with your upgraded Portworx Backup version.

Prerequisites​

Option 1: Install using the 'set' command​

Option 2: Install using the values-px-central.yaml file​

Verify the Portworx Backup upgrade​

Monitor upgrade completion​

Verify pod status​

Access the Portworx Backup web console​

What to do next​