Upgrade Portworx Backup on Non Air-Gapped Environments

Portworx Backup supports upgrades to version n from versions n-1 or n-2. For example, if you are on Portworx Backup version 2.10.x or 2.11.x, you can directly upgrade to 3.0.0. If you are on 2.9.x or earlier and want to upgrade to 3.0.0, you need to upgrade in a phased manner. First upgrade to an intermediate version (2.10.x or 2.11.x), and then upgrade to 3.0.0. For more information, see Upgrade matrix

To install or upgrade Portworx Backup using Argo CD, see Deploy Portworx Backup using Argo CD.

Upgrade Portworx Backup in non-airgapped environment

To upgrade to the required version of Portworx Backup:

Spec Details

1. Access Portworx Central portal.

2. Enter login credentials and make sure that you go through End-User License Agreement (EULA).

   If you are new to Portworx Central, click on Create account to generate your login credentials. You can also sign in with your organization’s OIDC identity provider, Google or Github account.

3. Click Sign In to access the Portworx Central portal.

4. On the home page, under Explore our Products, navigate to the Portworx Backup card. Then click Generate Backup Spec to open the Portworx Backup Install/upgrade page (Spec Details tab).

5. In the Spec Details tab provide the following values:

   • Backup Version: select the required version of Portworx Backup from the drop-down, here it is 3.0.0

   • Namespace: provide the name of the namespace where you want an instance of Portworx Backup to be installed

   • Select your environment: choose On-Premises or Cloud based on your storage environment

   • StorageClass Name: name of the StorageClass; see the tooltip for more details

     
     1. Release data:

     • Backup Version: select the required version of Portworx Backup from the drop-down

     • Namespace: provide the name of the namespace where you want an instance of Portworx Backup to be installed

     • Select your environment: choose On-Premises or Cloud based on your storage environment

     2. Configuration
        

     • StorageClass Name: name of the StorageClass; see the tooltip for more details
     note

     Defining the namespace and StorageClass is a one-time configuration step that should be completed during the initial installation. PVCs will be created using Namespace and StorageClass values you define in the SpecGen, and these values cannot be modified later during an upgrade.

     • Enable Rancher RBAC: select this checkbox if you are using Rancher for managing your Kubernetes clusters and want to enable Rancher's Role-Based Access Control (RBAC) for Portworx Backup. This feature can be enabled only if you have LDAP or PingIdentity as your identity provider. For more information, see Rancher RBAC Integration with Namespace Filtering and Rancher RBAC.

     • Use your OIDC: select this option only if your external authorization provider is Auth0 and fill in the following fields:

       • Endpoint
       • Client ID
       • Client Secret

       These values can be fetched from the Auth0 web console.

   • Use existing Prometheus: select this checkbox if you want to use your existing Prometheus stack to monitor Portworx Backup and enter the values for the following fields:

     • Prometheus Endpoint: enter details of the endpoint where your Prometheus is installed

     • Alertmanager Endpoint: enter details of the endpoint where your Alertmanager is installed

     • Prometheus secret name: enter secret name of your Prometheus stack

     • Alertmanager secret name: enter secret name of your Alertmanager

     • Custom email template from PX-Backup: select to upload Portworx Backup's custom email template to your pre-configured Alertmanager for email notifications

       By default, persistent volume size for Prometheus server is 5 GB, if you need more storage, use the following command during the upgrade from previous versions of Portworx Backup to 3.0.0:

       --set persistentStorage.prometheus.storage=8Gi,persistentStorage.prometheus.retentionSize=7360MB

       Replace 7360MB with 92% of your chosen prometheus.storage value in MB if you set a different size.

       The command above resets the Prometheus server's persistent volume size to 8 GB. You can set the required storage based on your needs.

   • Proxy Configuration: select this checkbox if you have a proxy server configured in your environment and enter the values for the following fields:

     • Unauthenticated: choose this if you have an unauthenticated proxy server
       • HTTP Proxy: proxy server URL for HTTP proxy
       • HTTPS Proxy: proxy server URL for HTTPS proxy
       • NO PROXY: comma-separated list of hostnames, IPs, or domains that should bypass the proxy settings
     • Authenticated/CA: choose this option if your cluster is behind a proxy server with authentication or CA

       • Proxy configuration secret: name of the kubernetes proxy configuration secret created in Portworx Backup namespace holding the proxy configuration

   1. Custom Registry

      
      • Use custom registry: applicable only for air-gapped environments, do not select this check-box for non-airgapped system.

   2. Database Credentials: This section configures database passwords for the various database components used by Portworx Backup. For guidelines on how to set the database credentials, see Password Policy.

      • MySQL Root User Password: root password for MySQL database

      • Postgres User Password: password for PostgreSQL user

      • MongoDB PX-Backup User Password: password for MongoDB PX-Backup user

      • MongoDB Root User Password: root password for MongoDB database

      • MongoDB Replica Set Key: key for MongoDB replica set authentication

      • Encrypt MongoDB: select this checkbox to enable encryption at rest for MongoDB database

      • MongoDB Master Encryption Key: Master encryption key for MongoDB encryption at rest

        caution

        Safeguarding your encryption key is vital to prevent permanent data loss. If the key is lost, you will be unable to access your encrypted data, as it is the only means of decryption. Without it, the data is rendered completely inaccessible and cannot be recovered. Note that encryption keys cannot be rotated after they are set.

6. Click Next to navigate to Finish tab.

Navigate to the Finish tab at the top to execute few commands to complete the installation.

Finish

Finish tab

Finish tab provides you with the generated Kubernetes manifests and Helm commands needed to complete the installation of Portworx Backup in your environment.

1. In the Finish tab:

Step 1

1. Copy the YAML below (command under Step 1) to your terminal and run it to create a Kubernetes secret containing database credentials and configuration parameters for Portworx Backup components.

   pxc-credentials secret

   kubectl apply -f - <<EOF
   apiVersion: v1
   kind: Namespace
   metadata:
     name: <pxb-namespace>
   ---
   apiVersion: v1
   kind: Secret
   metadata:
     name: pxc-credentials
     namespace: <pxb-namespace>
   data:
     mongodb-px-backup-password: <base64-encoded-mongodb-password>
     mongodb-root-password: <base64-encoded-mongodb-root-password>
     mongodb-replica-set-key: <base64-encoded-mongodb-replica-set-key>
     mongodb-master-encryption-key: <base64-encoded-mongodb-master-encryption-key>
     postgresql-password: <base64-encoded-postgresql-password>
     mysql-password: <base64-encoded-mysql-password>
   EOF

   The command creates the specified namespace (for example, central) and generates a pxc-credentials secret containing database passwords. All sensitive data is automatically base64-encoded for security, and the database credentials include password, replica set, and encryption key for MongoDB, only passwords for PostgreSQL and MySQL components of Portworx Backup.

   If pxc-credentials secret is not set, installing or upgrading Portworx Backup will fail with the following error:

   time="<UTC Timestamp>" level=fatal msg="Pre-install Hook failed: RunPreInstall: failed to validate custom passwords: ValidateCustomPasswordSecret: error validating pxc-credentials secret: secret pxc-credentials not found in namespace central"

Step 2

1. Execute the following command to add the helm repository to your cluster and update it:

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

Step 3

You can upgrade Portworx Backup either with default options or with advanced options based on your environment. To upgrade Portworx Backup with default options, go with Install using set command. For upgrade with advanced options, go with Install using the values-px-central.yaml file.

Option 1: Install using the ‘set’ command

To upgrade Portworx Backup with default or basic options:

1. 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, as it can put the cluster into a bad state.

   Sample command:

   helm upgrade px-central charts/px-central --namespace central --version <Variable name=”pxbVer_3.0.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.

2. After you are done with providing and appending all the required parameters for upgrade, verify the command for accuracy.

3. Now copy and run the command in the terminal to upgrade Portworx Backup.

OR

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

To upgrade Portworx Backup with advanced options:

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

2. Rename this as values-px-central-<pxb-release-version>.yaml. Where <pxb-release-version> is the Portworx Backup version you want to install.

3. Set the values for the following keys to true based on the service mesh deployed in your Portworx Backup cluster. By default, istio.enabled and linkerd.enabled are set to false. hostName is mandatory only if multiple applications use the same prefix "/":

   istio:
     enabled: true
     hostName: ""
   linkerd:
     enabled: true

4. Save the yaml file for the changes made and validate the values.

5. 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 to the required latest version.

   The above command retrieves the values used to configure the px-central Helm release with helm get values, scoped to the specified namespace (--namespace <pxb-namespace>, such as px-backup), and outputs them in YAML format (-o yaml). The results are then redirected into a file called values-current.yaml, allowing you to review, back up, or modify the configuration for future use, such as during an upgrade.

6. Compare the files you obtained from Step 2 and Step 5, and update the new values-px-central-<pxb-release-version>.yaml if required to carry all the customizations you have made in 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.

7. (Optional) Execute this step only if you have configured Prometheus and Grafana following the steps in Configure Prometheus and Grafana. Delete the Prometheus operator Deployment to avoid upgrade conflicts:

   kubectl delete deploy prometheus-operator -n <pxb-namespace>

   Where <pxb-namespace> is the namespace in which you are planning to deploy Portworx Backup.

8. Delete the post install hook job:

   kubectl delete job pxcentral-post-install-hook --namespace <pxb-namespace>

   Where <pxb-namespace> is the namespace in which you are planning to deploy Portworx Backup.

   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.

9. Now copy and execute the command under Install using the values-px-central.yaml file in your terminal to complete the upgrade:

   helm upgrade px-central portworx/px-central --namespace central --version <Variable name="pxbVer_3.0.0"/> -f values-px-central.yaml

   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. Ensure that you update the Helm command timeout parameter to 120m as shown in the following command:

    helm upgrade px-central portworx/px-central --namespace <pxb-namespace> --version <pxb-release-version> -f px-central-values-<pxb-release-version>.yaml --timeout=120m

   Where <pxb-release-version> is the Portworx Backup version you want to upgrade to.

10. Click Finish after you complete the upgrade installation.

    This activates the trial version of Portworx Backup. To upgrade to the enterprise version, apply a Portworx Backup license.

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