Upgrading the backup and restore software for an instance that uses NetApp Trident Protect (Upgrading from Version 5.2 to Version 5.4)

After you upgrade IBM® Software Hub, you must upgrade the cpdbr-tenant service and install the Backup Restore Orchestration service for the instance.

Upgrade phase

Updating your client workstation
Collecting required information
Preparing to run an upgrade in a restricted network
Preparing to run an upgrade from a private container registry
Upgrading prerequisite software
Upgrading shared cluster components
Preparing to upgrade an instance
Upgrading an instance
Setting up IBM Software Hub

Who needs to complete this task?

Cluster administrator A cluster administrator must complete this task.

When do you need to complete this task?

Repeat as needed If you have multiple instances of IBM Software Hub, repeat this task for each instance that you upgrade.

Before you begin

This task assumes that you have a workstation with the NetApp Trident Protect command-line interface (CLI) plug-in. For more information, see Install the Trident Protect CLI plugin in the NetApp Trident documentation:
Ensure that Python 3.11 or later is installed on the client workstation:
```
python3 --version
```
Download and extract the cpdops.tgz file from the IBM/cpd-cli repository on GitHub. Ensure that you download the file that corresponds to:
- The version of IBM Software Hub that is installed.
- The hardware on your cluster.

Best practice: You can run the commands in this task exactly as written using the installation environment variables. Ensure that you added the new environment variables from Updating your environment variables script.

In addition, ensure that you source the environment variables before you run the commands in this task.

About this task

To ensure that you can back up this instance of IBM Software Hub with NetApp Trident Protect, you must:

Give the service accounts for the Backup Restore Orchestration service the edit cluster role on the specified projects:

Service account	Projects	Details
`${BR_OPERATOR_SA}`	Backup Restore Orchestration service	The Red Hat® OpenShift® Container Platform `edit` role enables the Backup Restore Orchestration service operator to modify resources in the specified project.
`${BR_OPERATOR_JOB_SA}`	Operators project Operands project Any tethered projects	The Red Hat OpenShift Container Platform `edit` role enables the Backup Restore Orchestration service jobs to modify resources in the specified projects. For example, the service can use this role to patch a custom resource to put a service in maintenance mode.

Upgrade the cpdbr-tenant service.
Install the Backup Restore Orchestration service

Procedure

Log in to Red Hat OpenShift Container Platform as a cluster administrator.
```
${OC_LOGIN}
```
Remember: OC_LOGIN is an alias for the oc login command.

Update the Data Protection Application:

Get the name of the Data Protection Application:
```
oc get dpa \
--namespace=${OADP_PROJECT}
```
The default name is dpa-sample.
Set the DPA_NAME environment variable to the name of the Data Protection Application:
```
export DPA_NAME=<DPA-name>
```

Patch the Data Protection Application custom resource.

The command that you run depends on where your cluster pulls images from:

IBM Entitled Registry

oc patch dataprotectionapplication ${DPA_NAME} \
--namespace=${OADP_PROJECT} \
--type=json \
-p='[
  {
    "op": "replace",
    "path": "/spec/configuration/velero/customPlugins",
    "value": \[ 
      { 
        "image": "icr.io/cpopen/cpfs/cps-oadp-plugins:latest", 
        "name": "cpfs-oadp-plugin" 
      },
      { 
        "image": "icr.io/cpopen/cpd/cpdbr-velero-plugin:${VERSION}",
        "name": "cpdbr-velero-plugin" 
      },
      { 
        "image": "icr.io/cpopen/cpd/swhub-velero-plugin:${VERSION}", 
        "name": "swhub-velero-plugin" 
      },
      { 
        "image": "icr.io/db2u/db2u-velero-plugin:${VERSION}",
        "name": "db2u-velero-plugin" 
      } 
    \]
  }
]'

Private container registry

oc patch dataprotectionapplication ${DPA_NAME} \
--namespace=${OADP_PROJECT} \
--type=json \
-p='[
  {
    "op": "replace",
    "path": "/spec/configuration/velero/customPlugins",
    "value": \[ 
      { 
        "image": "${PRIVATE_REGISTRY_LOCATION}/cpopen/cpfs/cpfs-oadp-plugins:latest", 
        "name": "cpfs-oadp-plugin" 
      },
      { 
        "image": "${PRIVATE_REGISTRY_LOCATION}/cpopen/cpd/cpdbr-velero-plugin:${VERSION}",
        "name": "cpdbr-velero-plugin" 
      },
      { 
        "image": "${PRIVATE_REGISTRY_LOCATION}/cpopen/cpd/swhub-velero-plugin:${VERSION}", 
        "name": "swhub-velero-plugin" 
      },
      { 
        "image": "${PRIVATE_REGISTRY_LOCATION}/db2u/db2u-velero-plugin:${VERSION}",
        "name": "db2u-velero-plugin" 
      } 
    \]
  }
]'

Upgrade the cpdbr-tenant service.

The command that you run depends on where your cluster pulls images from:

IBM Entitled Registry

cpd-cli oadp install \
--component=cpdbr-tenant \
--namespace=${OADP_PROJECT} \
--tenant-operator-namespace=${PROJECT_CPD_INST_OPERATORS} \
--skip-recipes \
--upgrade=true \
--log-level=debug \
--verbose

Private container registry

cpd-cli oadp install \
--component=cpdbr-tenant \
--namespace=${OADP_PROJECT} \
--tenant-operator-namespace=${PROJECT_CPD_INST_OPERATORS} \
--private_registry_location=${PRIVATE_REGISTRY_LOCATION} \
--skip-recipes \
--upgrade=true \
--log-level=debug \
--verbose

Confirm that the required cluster role and cluster role binding were created in the ${PROJECT_INST_BR_SVC} when you installed the cpdbr-tenant service.

If they do not exist, the command creates them.

BINDING_NAME="cpdbr-tenant-service-crb-${PROJECT_CPD_INST_OPERATORS}"
SHOULD_ADD=false

# Check if the exact combination of SA name and namespace exists
if oc get clusterrolebinding ${BINDING_NAME} -o json | \
   jq -e ".subjects[]? | select(.kind==\"ServiceAccount\" and .name==\"${BR_OPERATOR_JOB_SA}\" and .namespace==\"${PROJECT_INST_BR_SVC}\")" > /dev/null 2>&1; then
  echo "ServiceAccount ${BR_OPERATOR_JOB_SA} already exists in namespace ${PROJECT_INST_BR_SVC}"
else
  echo "ServiceAccount ${BR_OPERATOR_JOB_SA} in namespace ${PROJECT_INST_BR_SVC} not found, adding"
  SHOULD_ADD=true
fi

# Add the subject if needed
if [ "${SHOULD_ADD}" = true ]; then
  oc patch clusterrolebinding ${BINDING_NAME} --type=json -p="[
    {
      \"op\": \"add\",
      \"path\": \"/subjects/-\",
      \"value\": {
        \"kind\": \"ServiceAccount\",
        \"name\": \"${BR_OPERATOR_JOB_SA}\",
        \"namespace\": \"${PROJECT_INST_BR_SVC}\"
      }
    }
  ]"
fi

Set up a Python virtual environment on the client workstation:
1. Create a Python virtual environment:
```
chmod +x ./venv.sh
./venv.sh
```
2. Activate the Python virtual environment:
```
source venv/bin/activate
```
Change to the directory where you extracted the cpdops.tgz file. Then navigate to the cpdops/trident-protect directory.

Update the NetApp Trident Protect application and execution hook custom resources.

The command that you run depends on where your cluster pulls images from:

IBM Entitled Registry

python cpd-trident-protect.py upgrade \
--appvault_name=${NETAPP_TRIDENT_PROTECT_APP_VAULT} \
--application_name=cpd-operators-tenant \
--trident_protect_operator_ns=${PROJECT_NETAPP_TRIDENT_PROTECT} \
--cpd_operator_ns=${PROJECT_CPD_INST_OPERATORS}

Private container registry

python cpd-trident-protect.py upgrade \
--appvault_name=${NETAPP_TRIDENT_PROTECT_APP_VAULT} \
--application_name=cpd-operators-tenant \
--trident_protect_operator_ns=${PROJECT_NETAPP_TRIDENT_PROTECT} \
--cpd_operator_ns=${PROJECT_CPD_INST_OPERATORS} \
--private_registry_location=${PRIVATE_REGISTRY_LOCATION}

Install the Backup Restore Orchestration service for the instance:

Instances without tethered projects

cpd-cli manage apply-br \
--license_acceptance=true \
--release=${VERSION} \
--patch_id=${PATCH_ID} \
--br_tool=trident-protect \
--trident_protect_ns=${PROJECT_NETAPP_TRIDENT_PROTECT} \
--trident_protect_appvault_name=${NETAPP_TRIDENT_PROTECT_APP_VAULT} \
--br_operator_ns=${PROJECT_INST_BR_SVC} \
--operator_ns=${PROJECT_CPD_INST_OPERATORS} \
--instance_ns=${PROJECT_CPD_INST_OPERANDS} \
--image_pull_prefix=${IMAGE_PULL_PREFIX} \
--image_pull_secret=${IMAGE_PULL_SECRET} \
--cpdbr_tenant_service_image_prefix=${IMAGE_PULL_PREFIX}/cpopen/cpd/cpdbr-oadp

Instances with tethered projects

cpd-cli manage apply-br \
--license_acceptance=true \
--release=${VERSION} \
--patch_id=${PATCH_ID} \
--br_tool=trident-protect \
--trident_protect_ns=${PROJECT_NETAPP_TRIDENT_PROTECT} \
--trident_protect_appvault_name=${NETAPP_TRIDENT_PROTECT_APP_VAULT} \
--br_operator_ns=${PROJECT_INST_BR_SVC} \
--operator_ns=${PROJECT_CPD_INST_OPERATORS} \
--instance_ns=${PROJECT_CPD_INST_OPERANDS} \
--tethered_instance_ns=${PROJECT_CPD_INSTANCE_TETHERED_LIST} \
--image_pull_prefix=${IMAGE_PULL_PREFIX} \
--image_pull_secret=${IMAGE_PULL_SECRET}
--cpdbr_tenant_service_image_prefix=${IMAGE_PULL_PREFIX}/cpopen/cpd/cpdbr-oadp

Give the ${BR_OPERATOR_SA} service account the edit cluster role on the required projects:

oc create rolebinding bros-rolebinding-edit \
--clusterrole=edit \
--serviceaccount=${PROJECT_CPD_INST_BR_SVC}:${BR_OPERATOR_SA} \
-n ${PROJECT_CPD_INST_BR_SVC}

oc label rolebinding bros-rolebinding-edit \
-n ${PROJECT_CPD_INST_BR_SVC} \
component-id=br-orchestration \
icpdsupport/addOnId=bros

Give the ${BR_OPERATOR_JOB_SA} service account the edit cluster role on the required projects:

# Assign the edit role in the operators project
# =======================================================================================
oc create rolebinding bros-job-sa-rb-${BR_OPERATOR_JOB_SA} \
--clusterrole=edit \
--serviceaccount=${PROJECT_CPD_INST_BR_SVC}:${BR_OPERATOR_JOB_SA} \
-n ${PROJECT_CPD_INST_OPERATORS}

oc label rolebinding bros-job-sa-rb-${BR_OPERATOR_JOB_SA} \
-n ${PROJECT_CPD_INST_OPERATORS} \
component-id=br-orchestration \
icpdsupport/addOnId=bros

# Assign the edit role in the operands project
# =======================================================================================
oc create rolebinding bros-job-sa-rb-${BR_OPERATOR_JOB_SA} \
--clusterrole=edit \
--serviceaccount=${PROJECT_CPD_INST_BR_SVC}:${BR_OPERATOR_JOB_SA} \
-n ${PROJECT_CPD_INST_OPERANDS}


oc label rolebinding bros-job-sa-rb-${BR_OPERATOR_JOB_SA} \
-n ${PROJECT_CPD_INST_OPERANDS} \
component-id=br-orchestration \
icpdsupport/addOnId=bros

if [ -n "${PROJECT_CPD_INSTANCE_TETHERED_LIST}" ]; then
    IFS=',' read -ra TETHERED_NS_LIST <<< "${PROJECT_CPD_INSTANCE_TETHERED_LIST}"
    
    for TETHERED_NS in "${TETHERED_NS_LIST[@]}"; do
      oc create rolebinding bros-job-sa-rb-${BR_OPERATOR_JOB_SA} \
      --clusterrole=edit \
      --serviceaccount=${PROJECT_CPD_INST_BR_SVC}:${BR_OPERATOR_JOB_SA} \
      -n ${TETHERED_NS}
      
      oc label rolebinding bros-job-sa-rb-${BR_OPERATOR_JOB_SA} \
      -n ${TETHERED_NS} \
      component-id=br-orchestration \
      icpdsupport/addOnId=bros

    done
fi

Restore If you plan to restore this instance to a different project or to a different cluster, you must install the cpdbr-tenant service role-based access control and the Backup Restore Orchestration service role-based access control.

Ensure that you complete the appropriate steps based on where you plan to restore the instance:

Restore to a different namespace on the same cluster

If you want to restore the instance to a different namespace on the same cluster:

Install the cpdbr-tenant service role-based access control:

cpd-cli oadp install \
--component=cpdbr-tenant \
--namespace=${OADP_PROJECT} \
--tenant-operator-namespace=${PROJECT_CPD_INST_OPERATORS_NEW} \
--skip-recipes \
--rbac-only=true \
--log-level=debug \
--verbose

Install the Backup Restore Orchestration service role-based access control.

Instances without tethered projects

cpd-cli manage apply-br \
--license_acceptance=true \
--release=${VERSION} \
--patch_id=${PATCH_ID} \
--br_tool=trident-protect \
--oadp_ns=${OADP_PROJECT} \
--ignore_tenant_ns_resources \
--trident_protect_ns=${PROJECT_NETAPP_TRIDENT_PROTECT} \
--trident_protect_application_name=${NETAPP_TRIDENT_PROTECT_APP_VAULT} \
--br_operator_ns=${PROJECT_INST_BR_SVC_NEW} \
--operator_ns=${PROJECT_CPD_INST_OPERATORS_NEW} \
--instance_ns=${PROJECT_CPD_INST_OPERANDS_NEW} \
--image_pull_prefix=${IMAGE_PULL_PREFIX} \
--image_pull_secret=${IMAGE_PULL_SECRET} \
--cpdbr_tenant_service_image_prefix=${IMAGE_PULL_PREFIX}/cpopen/cpd/cpdbr-oadp

Instances with tethered projects

cpd-cli manage apply-br \
--license_acceptance=true \
--release=${VERSION} \
--patch_id=${PATCH_ID} \
--br_tool=trident-protect \
--oadp_ns=${OADP_PROJECT} \
--ignore_tenant_ns_resources \
--trident_protect_ns=${PROJECT_NETAPP_TRIDENT_PROTECT} \
--trident_protect_application_name=${NETAPP_TRIDENT_PROTECT_APP_VAULT} \
--br_operator_ns=${PROJECT_INST_BR_SVC_NEW} \
--operator_ns=${PROJECT_CPD_INST_OPERATORS_NEW} \
--instance_ns=${PROJECT_CPD_INST_OPERANDS_NEW} \
--tethered_instance_ns=${PROJECT_CPD_INSTANCE_TETHERED_LIST_NEW} \
--image_pull_prefix=${IMAGE_PULL_PREFIX} \
--image_pull_secret=${IMAGE_PULL_SECRET} \
--cpdbr_tenant_service_image_prefix=${IMAGE_PULL_PREFIX}/cpopen/cpd/cpdbr-oadp

Restore to the same namespace on a different cluster

If you want to restore the instance to the same namespace on a different cluster, complete the following steps on the target cluster:

Install the cpdbr-tenant service role-based access control:

cpd-cli oadp install \
--component=cpdbr-tenant \
--namespace=${OADP_PROJECT} \
--tenant-operator-namespace=${PROJECT_CPD_INST_OPERATORS} \
--skip-recipes \
--rbac-only=true \
--log-level=debug \
--verbose

Install the Backup Restore Orchestration service role-based access control.

Instances without tethered projects

cpd-cli manage apply-br \
--license_acceptance=true \
--release=${VERSION} \
--patch_id=${PATCH_ID} \
--br_tool=trident-protect \
--oadp_ns=${OADP_PROJECT} \
--ignore_tenant_ns_resources \
--trident_protect_ns=${PROJECT_NETAPP_TRIDENT_PROTECT} \
--trident_protect_application_name=${NETAPP_TRIDENT_PROTECT_APP_VAULT} \
--br_operator_ns=${PROJECT_INST_BR_SVC} \
--operator_ns=${PROJECT_CPD_INST_OPERATORS} \
--instance_ns=${PROJECT_CPD_INST_OPERANDS} \
--image_pull_prefix=${IMAGE_PULL_PREFIX} \
--image_pull_secret=${IMAGE_PULL_SECRET} \
--cpdbr_tenant_service_image_prefix=${IMAGE_PULL_PREFIX}/cpopen/cpd/cpdbr-oadp

Instances with tethered projects

cpd-cli manage apply-br \
--license_acceptance=true \
--release=${VERSION} \
--patch_id=${PATCH_ID} \
--br_tool=trident-protect \
--oadp_ns=${OADP_PROJECT} \
--ignore_tenant_ns_resources \
--trident_protect_ns=${PROJECT_NETAPP_TRIDENT_PROTECT} \
--trident_protect_application_name=${NETAPP_TRIDENT_PROTECT_APP_VAULT} \
--br_operator_ns=${PROJECT_INST_BR_SVC} \
--operator_ns=${PROJECT_CPD_INST_OPERATORS} \
--instance_ns=${PROJECT_CPD_INST_OPERANDS} \
--tethered_instance_ns=${PROJECT_CPD_INSTANCE_TETHERED_LIST} \
--image_pull_prefix=${IMAGE_PULL_PREFIX} \
--image_pull_secret=${IMAGE_PULL_SECRET} \
--cpdbr_tenant_service_image_prefix=${IMAGE_PULL_PREFIX}/cpopen/cpd/cpdbr-oadp

Restore to a different namespace on a different cluster

If you want to restore the instance to a different namespace on a different cluster, complete the following steps on the target cluster:

Install the cpdbr-tenant service role-based access control:

cpd-cli oadp install \
--component=cpdbr-tenant \
--namespace=${OADP_PROJECT} \
--tenant-operator-namespace=${PROJECT_CPD_INST_OPERATORS_NEW} \
--skip-recipes \
--rbac-only=true \
--log-level=debug \
--verbose

Install the Backup Restore Orchestration service role-based access control.

Instances without tethered projects

cpd-cli manage apply-br \
--license_acceptance=true \
--release=${VERSION} \
--patch_id=${PATCH_ID} \
--br_tool=trident-protect \
--oadp_ns=${OADP_PROJECT} \
--ignore_tenant_ns_resources \
--trident_protect_ns=${PROJECT_NETAPP_TRIDENT_PROTECT} \
--trident_protect_application_name=${NETAPP_TRIDENT_PROTECT_APP_VAULT} \
--br_operator_ns=${PROJECT_INST_BR_SVC_NEW} \
--operator_ns=${PROJECT_CPD_INST_OPERATORS_NEW} \
--instance_ns=${PROJECT_CPD_INST_OPERANDS_NEW} \
--image_pull_prefix=${IMAGE_PULL_PREFIX} \
--image_pull_secret=${IMAGE_PULL_SECRET} \
--cpdbr_tenant_service_image_prefix=${IMAGE_PULL_PREFIX}/cpopen/cpd/cpdbr-oadp

Instances with tethered projects

cpd-cli manage apply-br \
--license_acceptance=true \
--release=${VERSION} \
--patch_id=${PATCH_ID} \
--br_tool=trident-protect \
--oadp_ns=${OADP_PROJECT} \
--ignore_tenant_ns_resources \
--trident_protect_ns=${PROJECT_NETAPP_TRIDENT_PROTECT} \
--trident_protect_application_name=${NETAPP_TRIDENT_PROTECT_APP_VAULT} \
--br_operator_ns=${PROJECT_INST_BR_SVC_NEW} \
--operator_ns=${PROJECT_CPD_INST_OPERATORS_NEW} \
--instance_ns=${PROJECT_CPD_INST_OPERANDS_NEW} \
--tethered_instance_ns=${PROJECT_CPD_INSTANCE_TETHERED_LIST} \
--image_pull_prefix=${IMAGE_PULL_PREFIX} \
--image_pull_secret=${IMAGE_PULL_SECRET} \
--cpdbr_tenant_service_image_prefix=${IMAGE_PULL_PREFIX}/cpopen/cpd/cpdbr-oadp

What to do next

Now that you've upgraded the backup and restore software for the instance, you're ready to complete Upgrading privileged monitors (Upgrading from Version 5.2 to Version 5.4)