Upgrade PXB on Non Air-Gapped Environments

Portworx Backup supports upgrades to version n from versions n-1 or n-2 versions. For example, if you are on Portworx Backup version 2.7.x, you can directly upgrade to 2.10.0. Suppose, if you are on 2.5.x and you wish to upgrade to 2.10.0, you need to upgrade in phased manner. Firstly upgrade from version 2.5.x to 2.7.x, and then upgrade from version 2.7.x to 2.10.0.

Refer the Argo CD install topic for install/upgrade PXB through Argo CD.

Upgrade Portworx Backup in non-airgapped Environment

To upgrade to 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 2.10.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, refer 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, refer 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, refer to PXB Rancher RBAC and Rancher RBAC.

     • Use your OIDC: select this option only if your external authorization provider is Auth0 and key 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 have 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 2.10.0:

       --set persistentStorage.prometheus.storage=8Gi, persistentStorage.prometheus.retentionSize=<92% of prometheus.storage in MB>7360MB

       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 proxy server configured in your environment and enter the values for the following fields:

     • Unathenticated: choose this if you have unathenticated 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 pxb 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, refer to 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 below yaml (command under Step 1) to your terminal and run tocreate 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.

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

   Sample command:

   helm upgrade px-central charts/px-central --namespace central --version 2.10.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 PXB version you want to install.

3. Set the values for the below keys as true based on the service mesh you have deployed in PXB cluster. Note that by default, istio.enabled and linkerd.enabled are set to false. hostName is mandatory only if multiple application uses 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 PXB 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 ii and Step v, 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 mentioned in this topic Configure Prometheus and Grafana. Delete the Prometheus operator deployment upgrade to avoid conflicts:

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

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

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

   note

   If you have enabled health check, deletion of post install hook job is automatically taken care. If no, you need to delete manually with the above command.

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 --create-namespace --version 2.10.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 it is necessary to increase the timeout to 120 minutes. Also ensure that, you update the helm command timeout parameter to 120m without fail 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 PXB 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.

    note

    If you are on Portworx Backup version 2.0.0 and want to upgrade to version 2.0.1 or 2.0.1 or 2.1.x or 2.2.x, then set the administrator password in the helm upgrade command as shown below:

    helm upgrade px-central portworx/px-central --namespace <pxb-namespace> --version <pxb-release-version> --set oidc.centralOIDC.defaultPassword=<current-admin-password> -f values.yaml

    Where <pxb-namespace> is the namespace in which you are planning to deploy PXB and <pxb-release-version> is the PXB version you want to upgrade to.