Upgrading IBM Software Hub (Upgrading from Version 5.2 to Version 5.4)

To upgrade an instance of IBM Software Hub, you must grade the required operators and custom resources 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?

Instance administrator An instance administrator can complete this task.

When do you need to complete this task?

Repeat as needed If you have multiple instances of IBM Software Hub on the cluster, complete this task for each instance that you want to upgrade.

Before you begin

Best practice: You can run many of 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.

Service-specific prerequisite tasks

If you have any of the following services on this instance of IBM Software Hub, complete the required steps before you upgrade IBM Software Hub:

watsonx Code Assistant

Delete the ibm-granite-20b-code-javaenterprise-v2 InferenceService object:

oc delete isvc ibm-granite-20b-code-javaenterprise-v2 \
-n ${PROJECT_CPD_INST_OPERANDS} \
--ignore-not-found

watsonx Code Assistant for Red Hat Ansible Lightspeed

Delete the ibm-granite-3b-code-v1 and ibm-granite-20b-code-8k-ansible InferenceService object:

oc delete isvc ibm-granite-3b-code-v1 ibm-granite-20b-code-8k-ansible \
-n ${PROJECT_CPD_INST_OPERANDS} \
--ignore-not-found

About this task

Use the cpd-cli manage install-components command to upgrade the required operators and custom resources for an instance of IBM Software Hub.

Note: The install-components command in this topic includes the --run_storage_tests option. It is strongly recommended that you run the command with the --run_storage_tests option to enure that the storage in your environment meets the minimum requirements for performance.

If your storage does not meet the minimum requirements, you can remove the --run_storage_tests option to continue the upgrade. However, your environment is likely to encounter problems because of issues with your storage.

Procedure

Log the cpd-cli in to the Red Hat OpenShift® Container Platform cluster:
```
${CPDM_OC_LOGIN}
```
Remember: CPDM_OC_LOGIN is an alias for the cpd-cli manage login-to-ocp command.

Review the license terms for the software that you plan to install.

The licenses are available online. However, some licenses are not included in the get-license command. If you don't see the license that you purchased, you can search for the license on IBM Terms.

See all available license URLs

cpd-cli manage get-license \
--release=${VERSION}

See the URL for a specific license

Run the appropriate commands based on the license or licenses that you purchased.

IBM Cloud Pak for Data Enterprise Edition

cpd-cli manage get-license \
--release=${VERSION} \
--license_types=EE

IBM Cloud Pak for Data Standard Edition

cpd-cli manage get-license \
--release=${VERSION} \
--license_types=SE

IBM Data Gate for watsonx

cpd-cli manage get-license \
--release=${VERSION} \
--license_types=DGWXD

IBM Data Product Hub Cartridge

cpd-cli manage get-license \
--release=${VERSION} \
--license_types=DPH

Data Replication

Run the appropriate command based on the license that you purchased:

IBM Data Replication Cartridge

cpd-cli manage get-license \
--release=${VERSION} \
--license_types=IDRC

IBM InfoSphere® Data Replication Cartridge

cpd-cli manage get-license \
--release=${VERSION} \
--license_types=IIDRC

IBM Data Replication Modernization

cpd-cli manage get-license \
--release=${VERSION} \
--license_types=IDRM

IBM InfoSphere Data Replication Modernization

cpd-cli manage get-license \
--release=${VERSION} \
--license_types=IIDRM

IBM Data Replication for Db2® z/OS® Cartridge

cpd-cli manage get-license \
--release=${VERSION} \
--license_types=IDRZOS

IBM InfoSphere Data Replication for watsonx.data™ Cartridge

cpd-cli manage get-license \
--release=${VERSION} \
--license_types=IIDRWXTO

IBM InfoSphere Data Replication Cartridge Add-on for IBM watsonx.data

cpd-cli manage get-license \
--release=${VERSION} \
--license_types=IIDRWXAO

Db2

Run the appropriate command based on the license that you purchased:

IBM Db2 Standard Edition Cartridge for IBM Cloud Pak for Data

cpd-cli manage get-license \
--release=${VERSION} \
--license_types=DB2SE

IBM Db2 Advanced Edition Cartridge for IBM Cloud Pak for Data

cpd-cli manage get-license \
--release=${VERSION} \
--license_types=DB2AE

IBM Knowledge Catalog Premium

cpd-cli manage get-license \
--release=${VERSION} \
--license_types=IKCP

IBM Knowledge Catalog Standard

cpd-cli manage get-license \
--release=${VERSION} \
--license_types=IKCS

IBM watsonx.ai

cpd-cli manage get-license \
--release=${VERSION} \
--license_types=WXAI

IBM watsonx Code Assistant

cpd-cli manage get-license \
--release=${VERSION} \
--license_types=WCA

IBM watsonx Code Assistant for Ansible

cpd-cli manage get-license \
--release=${VERSION} \
--license_types=WCAA

IBM watsonx.data

cpd-cli manage get-license \
--release=${VERSION} \
--license_types=WXD

IBM watsonx.data Premium Edition

cpd-cli manage get-license \
--release=${VERSION} \
--license_types=WXDP

Upgrade the required operators and custom resources for the instance.

Tip: Before you run this command against your cluster, you can preview the oc commands that this command will issue on your behalf by running the command with the --preview=true option.

The oc commands are saved to the preview.sh file in the work directory.

The command that you run depends on whether the instance includes tethered projects:

Instances without tethered projects

cpd-cli manage install-components \
--license_acceptance=true \
--components=cpd_platform \
--release=${VERSION} \
--patch_id=${PATCH_ID} \
--operator_ns=${PROJECT_CPD_INST_OPERATORS} \
--instance_ns=${PROJECT_CPD_INST_OPERANDS} \
--image_pull_prefix=${IMAGE_PULL_PREFIX} \
--image_pull_secret=${IMAGE_PULL_SECRET} \
--run_storage_tests=true \
--upgrade=true

Instances with tethered projects

cpd-cli manage install-components \
--license_acceptance=true \
--components=cpd_platform \
--release=${VERSION} \
--patch_id=${PATCH_ID} \
--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} \
--run_storage_tests=true \
--upgrade=true

Wait for the cpd-cli to return the following message before preceding to the next step:

[SUCCESS] ... The install-components command ran successfully.

If you have any custom RSI patches that patch zen pods or IBM Cloud Pak foundational services pods, reapply the patches:
1. Run the following command to get a list of the RSI patches in the operands project:
```
cpd-cli manage get-rsi-patch-info \
--cpd_instance_ns=${PROJECT_CPD_INST_OPERANDS} \
--all
```
2. If there are patches that apply to zen or IBM Cloud Pak foundational services pods, run the following command to apply your custom patches:
```
cpd-cli manage apply-rsi-patches \
--cpd_instance_ns=${PROJECT_CPD_INST_OPERANDS}
```
Optional: If you want to run a batch upgrade of the services that are installed on the instance, run the install-components command.
Tip: Before you run this command against your cluster, you can preview the oc commands that this command will issue on your behalf by running the command with the --preview=true option.
The oc commands are saved to the preview.sh file in the work directory.
```
cpd-cli manage install-components \
--license_acceptance=true \
--components=${COMPONENTS} \
--release=${VERSION} \
--patch_id=${PATCH_ID} \
--operator_ns=${PROJECT_CPD_INST_OPERATORS} \
--instance_ns=${PROJECT_CPD_INST_OPERANDS} \
--image_pull_prefix=${IMAGE_PULL_PREFIX} \
--image_pull_secret=${IMAGE_PULL_SECRET} \
--upgrade=true
```
Wait for the cpd-cli to return the following message before preceding to the next step:
```
[SUCCESS] ... The install-components command ran successfully.
```

Confirm that the status of the operands is Completed:

cpd-cli manage get-cr-status \
--cpd_instance_ns=${PROJECT_CPD_INST_OPERANDS}

Check the health of the resources in the operators project:

cpd-cli health operators \
--operator_ns=${PROJECT_CPD_INST_OPERATORS} \
--control_plane_ns=${PROJECT_CPD_INST_OPERANDS}

Confirm that the health check report returns the expected results:

Test	What the test checks	Expected result
`Pod Healthcheck`	For pods in the operators project, the status of each required pod is `Running`.	`[SUCCESS]`
`Pod Usage Healthcheck`	For pods in the operators project, the resource use for each pod is within the CPU and memory limits.	`[SUCCESS]`
`Cluster Service Versions Healthcheck`	For cluster service versions (CSVs) in the operators project, the phase of each CSV is `Succeeded`.	`[SUCCESS]`
`Catalog Source Healthcheck`	For catalog sources in the operators project, the last observed state of each catalog source is `Ready`.	`[SUCCESS]`
`Install Plan Healthcheck`	For operators in the operators project, the install plan approval for each operator is `Automatic`.	`[SUCCESS]`
`Subscriptions Healthchec`	For subscriptions in the operators project, there is an installed CSV for each subscription.	`[SUCCESS]`
`Persistent Volume Claim Healthcheck`	For persistent volume claims (PVCs) in the operators project, each PVC is bound. Note: There should not be any PVC in the operators project, so the test should be skipped.	`[SKIP...]`
`Deployment Healthcheck`	For deployments in the operators project, each deployment has the desired number of replicas.	`[SUCCESS]`
`Namespace Scopes Healthcheck`	For the `NamespaceScope` operator in the operators project, the projects that are specified in the `members` list exist.	`[SUCCESS]`
`Stateful Set Healthcheck`	For stateful sets in the operators project, the stateful sets have the desired number of replicas. Note: There should not be any stateful sets in the operators project, so the test should be skipped.	`[SKIP...]`
`Common Services Healthcheck`	For the `common-service commonservice` custom resource in the operators project, the phase of the custom resource is `Succeeded`.	`[SUCCESS]`
`Custom Resource Healthcheck`	For any other custom resources in the operators project, the phase of each custom resource is `Succeeded`. Note: There should not be any other custom resources in the operators project, so the test should be skipped.	`[SKIP...]`
`Operand Requests Healthcheck`	For operand requests in the operators project, the phase of each operand request is `Running`,	`[SUCCESS]`

Check the health of the resources in the operands project:

cpd-cli health operands \
--control_plane_ns=${PROJECT_CPD_INST_OPERANDS}

Confirm that the health check report returns the expected results:

Test	What the test checks	Expected result
`Pod Healthcheck`	For pods in the operands project, the status of each pod is `Running`.	`[SUCCESS]`
`Pod Usage Healthcheck`	For pods in the operands project, the resource use for each pod is within the CPU and memory limits.	`[SUCCESS]`
`EDB Cluster Healthcheck`	For EDB Postgres clusters in the operands project, the status of each cluster is `Cluster in healthy state`.	`[SUCCESS]`
`Persistent Volume Claim Healthcheck`	For persistent volume claims (PVCs) in the operands project, each PVC is bound.	`[SUCCESS]`
`Deployment Healthcheck`	For deployments in the operands project, each deployment has the desired number of replicas.	`[SUCCESS]`
`Stateful Set Healthcheck`	For stateful sets in the operands project, the stateful sets have the desired number of replicas.	`[SUCCESS]`
`Common Services Healthcheck`	For the `common-service commonservice` custom resource in the operands project, the phase of the custom resource is `Succeeded`.	`[SUCCESS]`
`Operand Requests Healthcheck`	For operand requests in the operands project, the phase of each operand request is `Running`.	`[SUCCESS]`
`Monitor Events Healthcheck`	The platform monitors are not generating any `Critical` events.	`[SUCCESS]`
`Custom Resource Healthcheck`	For custom resources in the operands project, the phase of each custom resource is `Succeeded`.	`[SUCCESS]`
`Platform Healthcheck`	That the pods for required platform microservices are `Running`.	`[SUCCESS]`

What to do next

Now that you've upgraded the IBM Software Hub control plane, you're ready to complete Updating the backup and restore software for an instance of IBM Software Hub (Upgrading from Version 5.2 to Version 5.4).

If you don't use the cpdbr service, see Upgrading the IBM Software Hub configuration admission controller webhook (Upgrading from Version 5.2 to Version 5.4)