Upgrading from IBM Software Hub Version 5.1 to Version 5.2

A Red Hat® OpenShift® Container Platform cluster administrator and instance administrator can work together to upgrade IBM Software Hub from Version 5.1 to Version 5.2.

Important: It is strongly recommended that you upgrade to Version 5.2.1 or later.

Upgrading to Version 5.2.0 is not recommended because you must manually apply fixes after you upgrade to 5.2.0.

The fixes are included in Version 5.2.1 and later.

Before you begin

Before you upgrade IBM Software Hub:
  1. Review the information in the Planning section.

    Specifically, ensure that you review the System requirements. Your cluster must have sufficient resources.

  2. Review the information in Planning an upgrade.
  3. Ensure that you have a copy of script that defines the installation environment variables for your deployment.

    The script enables you to run most of the installation and upgrade commands without modifying them.

  4. Best practice Backup your IBM Software Hub installation before you upgrade.

    In the event of an unrecoverable failure, you can use the backup to recover your existing installation. For details, see Backing up and restoring IBM Software Hub in the IBM Software Hub Version 5.1 documentation.

Upgrade overview

The upgrade is broken up into the following phases:

1. Updating client workstations

Before you upgrade IBM Software Hub, you must ensure that the workstation has the latest version of the cpd-cli and the olm-utils-v3 image.

User icon All administrators When icon Repeat as needed

What to do
  1. Complete Updating client workstations (Upgrading from Version 5.1 to Version 5.2).
  2. Go to 2. Collecting required information.

2. Collecting required information

To successfully upgrade your IBM Software Hub installation, you must have specific information about your environment.

User icon Operations team When icon Repeat as needed

What to do
  1. Complete Determining which components to upgrade (Upgrading from Version 5.1 to Version 5.2).
  2. If you use a private container registry, complete Determining which models and images to mirror to your private container registry (Upgrading from Version 5.1 to Version 5.2).
  3. Complete Updating your environment variables script (Upgrading from Version 5.1 to Version 5.2).
  4. Go to the appropriate section based on your environment:

3. Preparing to run upgrades in a restricted network

If you will run the IBM Software Hub upgrade commands in a restricted network, you must prepare the client workstations before you move them behind your firewall.

User icon All administrators When icon Repeat as needed

What to do
  1. Complete Obtaining the olm-utils-v3 image before running IBM Software Hub installation commands in a restricted network (Upgrading from Version 5.1 to Version 5.2).
  2. Complete Downloading CASE packages before running IBM Software Hub upgrade commands in a restricted network (Upgrading from Version 5.1 to Version 5.2).
  3. Go to the appropriate section based on your environment:

4. Preparing to run upgrades from a private container registry

User icon Different users need to complete the appropriate tasks.

When icon Some of these tasks can be completed once, but some of the tasks must be repeated for each user involved in the installation.

If you use a private container registry to host the IBM Software Hub software images, you must mirror the updated images from the IBM Entitled Registry to the private container registry.

a. Mirroring images to the private container registry

If you mirrored the images for IBM Software Hub Version 5.1 to a private container registry, you must mirror the images for Version 5.2 to the private container registry before you upgrade your installation.

User icon Registry administrator When icon Repeat as needed

What to do
  1. Complete the appropriate task for your environment in Mirroring images to a private container registry (Upgrading from Version 5.1 to Version 5.2).
  2. Go to b. Do users need to pull the olm-utils-v3 image from the private container registry?.
b. Do users need to pull the olm-utils-v3 image from the private container registry?

If the olm-utils-v3 image is available in the private container registry, you must update the cpd-cli to pull the image from the private container registry.

User icon All administrators When icon Repeat as needed

Options What to do
Your cluster is not in a restricted network and users can pull the image from the IBM Entitled Registry
  1. Go to 5. Upgrading prerequisite software.
Your cluster is not in a restricted network, but you want users to pull the image from the private container registry
  1. Complete Pulling the olm-utils-v3 image from the private container registry (Upgrading from Version 5.1 to Version 5.2).
  2. Go to 5. Upgrading prerequisite software.
Your cluster is in a restricted network
  1. Complete Pulling the olm-utils-v3 image from the private container registry (Upgrading from Version 5.1 to Version 5.2).
  2. Go to 5. Upgrading prerequisite software.

5. Upgrading prerequisite software

Several services have prerequisite software that must be upgraded by a cluster administrator.

User icon Cluster administrator When icon Most of these tasks can be completed once, but some of the tasks must be repeated if you have multiple instances of the service on the cluster.

Services with a dependency on prerequisite software
Prerequisite software Services with this prerequisite Upgrade this software if...
Node Feature Discovery Operator

An asterisk (*) indicates that the service requires GPU in some situations.

  • IBM Knowledge Catalog Premium *
  • IBM Knowledge Catalog Standard *
  • Watson Machine Learning *
  • Watson Studio Runtimes *
  • watsonx.ai™
  • watsonx Assistant *
  • Watsonx BI
  • watsonx Code Assistant™
  • watsonx Code Assistant for Red Hat Ansible® Lightspeed
  • watsonx Code Assistant for Z
  • watsonx Code Assistant for Z Agentic 5.2.1 and later
  • watsonx Code Assistant for Z Code Explanation
  • watsonx Code Assistant for Z Code Generation 5.2.1 and later
  • watsonx.data™ *
  • watsonx.data Premium
  • watsonx.data intelligence
  • watsonx™ Orchestrate *

You upgraded Red Hat OpenShift Container Platform and the operator is installed with installPlanApproval: Manual.
NVIDIA GPU Operator

An asterisk (*) indicates that the service requires GPU in some situations.

  • IBM Knowledge Catalog Premium *
  • IBM Knowledge Catalog Standard *
  • Watson Machine Learning *
  • Watson Studio Runtimes *
  • watsonx.ai
  • watsonx Assistant *
  • Watsonx BI
  • watsonx Code Assistant
  • watsonx Code Assistant for Red Hat Ansible Lightspeed
  • watsonx Code Assistant for Z
  • watsonx Code Assistant for Z Agentic 5.2.1 and later
  • watsonx Code Assistant for Z Code Explanation
  • watsonx Code Assistant for Z Code Generation 5.2.1 and later
  • watsonx.data *
  • watsonx.data Premium
  • watsonx.data intelligence
  • watsonx Orchestrate *

The version of the operator on your cluster has reached the end of support. For details, see NVIDIA GPU Operator Life Cycle in the

Red Hat OpenShift AI

An asterisk (*) indicates that the service requires Red Hat OpenShift AI in some situations.

  • IBM Knowledge Catalog Premium *
  • IBM Knowledge Catalog Standard *
  • watsonx.ai
  • watsonx Assistant *
  • Watsonx BI
  • watsonx Code Assistant
  • watsonx Code Assistant for Red Hat Ansible Lightspeed
  • watsonx Code Assistant for Z
  • watsonx Code Assistant for Z Agentic 5.2.1 and later
  • watsonx Code Assistant for Z Code Explanation
  • watsonx Code Assistant for Z Code Generation 5.2.1 and later
  • watsonx.data Premium
  • watsonx.data intelligence
  • watsonx Orchestrate *

The required version of Red Hat OpenShift AI depends on the version of IBM Software Hub that you plan to install.

You must upgrade this software if both of the following statements are true:
  • You plan to upgrade an instance of IBM Software Hub with services that have a dependency on Red Hat OpenShift AI.
  • You plan to upgrade to a version of IBM Software Hub that requires a newer version of Red Hat OpenShift AI.
Multicloud Object Gateway
  • Watson Discovery
  • Watson Speech services
  • watsonx Assistant
  • watsonx Orchestrate

You must upgrade Multicloud Object Gateway if you upgrade Red Hat OpenShift Container Platform.
Red Hat OpenShift Serverless Knative Eventing
  • watsonx Assistant
  • watsonx Orchestrate
You must upgrade Red Hat OpenShift Serverless Knative Eventing if any of the following statements is true:
  • There is a new version of the IBM Events Operator included with IBM Software Hub.
  • You upgrade Red Hat OpenShift Container Platform and the version of the Red Hat OpenShift Serverless Operator on your cluster is not supported on the version of OpenShift Container Platform that you are running.
  • The version of the Red Hat OpenShift Serverless Operator on your cluster is out of support.
Options What to do
The instance that you are upgrading does not include any services with a dependency on prerequisite software
  1. Go to 6. Upgrading shared cluster components.
You are upgrading services with a dependency on prerequisite software
  1. Complete Upgrading prerequisite software (Upgrading from Version 5.1 to Version 5.2).
  2. Go to 6. Upgrading shared cluster components.

6. Upgrading shared cluster components

Before you upgrade IBM Software Hub, you must upgrade the License Service and scheduling service. If the IBM Certificate manager is installed on the cluster, you must also upgrade the Certificate manager.

User icon Cluster administrator When icon Repeat as needed

What to do
  1. Complete Upgrading shared cluster components (Upgrading from Version 5.1 to Version 5.2).
  2. Go to 7. Preparing to upgrade an instance of IBM Software Hub.

7. Preparing to upgrade an instance of IBM Software Hub

Before you upgrade an instance of IBM Software Hub, a cluster administrator must prepare the instance for upgrade.

User icon Cluster administrator When icon Repeat as needed

a. Checking the health of your cluster

The IBM Software Hub command-line interface includes commands that you can use the validate the health of your cluster before you upgrade IBM Software Hub. If you do not validate the health of your cluster before you upgrade IBM Software Hub, you might encounter issues during the upgrade.

What to do
  1. Complete Checking the health of your cluster before upgrading IBM Software Hub (Upgrading from Version 5.1 to Version 5.2).
  2. Go to b. Do you need to reauthorize the instance administrator?.
b. Do you need to reauthorize the instance administrator?

If you gave an instance administrator the minimum role-based access control (RBAC) to install IBM Software Hub software, you must update the roles that are assigned to the user so that the user has sufficient privileges to upgrade the instance.

Options What to do
The cluster administrator will upgrade the instance
  1. Go to c. Do you need to update your entitlements?
An instance administrator will upgrade the instance, but the user has the admin role on the projects
  1. Go to c. Do you need to update your entitlements?
An instance administrator will upgrade the instance, and the user has the minimum permissions to install the software
  1. Complete Reauthorizing an instance administrator with the minimum RBAC to upgrade components (Upgrading from Version 5.1 to Version 5.2).
  2. Go to c. Do you need to update your entitlements?
c. Do you need to update your entitlements?
You are required to keep a record of the size of deployments to report to IBM as requested. The License Service measures your use against your license terms.
Options What to do
You are not changing the solutions or services associated with the instance
  1. Go to 8. Upgrading an instance of IBM Software Hub.
You are changing one or more solutions or services associated with the instance
  1. Complete the appropriate task for your environment in Applying your entitlements to monitor and report use against license terms (Upgrading from Version 5.1 to Version 5.2).
  2. Go to 8. Upgrading an instance of IBM Software Hub.

8. Upgrading an instance of IBM Software Hub

To upgrade an instance of IBM Software Hub, you must update the operators and operands (custom resources) that are associated with the instance.

User icon Instance administrator When icon Repeat as needed

a. Upgrading IBM Software Hub

To upgrade an instance of IBM Software Hub, you must grade the required operators and custom resources for the instance. After you upgrade the required operators for the instance, you must upgrade the operators for the services that are installed on the instance.

What to do
  1. Complete Upgrading IBM Software Hub (Upgrading from Version 5.1 to Version 5.2).
  2. Go to b. Upgrading the cpdbr service.
b. Upgrading the cpdbr service

You must upgrade the cpdbr service after you upgrade IBM Software Hub.

Options What to do
You do not use the cpdbr service to back up and restore your IBM Software Hub deployment
  1. Go to 9. Upgrading the privileged monitoring service.
You use the cpdbr service to back up and restore your IBM Software Hub deployment
  1. Complete Updating the cpdbr service (Upgrading from Version 5.1 to Version 5.2).
  2. Go to 9. Upgrading the privileged monitoring service.

9. Upgrading the privileged monitoring service

Privileged monitors provide additional information about the health of the cluster and resources that are not typically included in the platform monitors. If you installed the privileged monitors, a cluster administrator must upgrade the monitors when you upgrade IBM Software Hub.

User icon Cluster administrator When icon Repeat as needed

Monitors provided by the privileged monitoring service
Cluster operator status check (check-cluster-operator-status)
Checks the status of the cluster operators that comprise the Red Hat OpenShift Container Platform infrastructure to determine whether:
  • All of the operators are AVAILABLE
  • Any of the operators are DEGRADED
Network status check (check-network-status)
Checks the status of the PodNetworkConnectivityCheck objects for cluster resources to determine whether the objects are Reachable.
Node imbalance status check (check-node-imbalance-status)
Checks whether vCPU requests are balanced across nodes or whether one node is supporting a disproportionately high load.
Node status check (check-node-status)
Checks whether the nodes on the cluster are ready and whether the nodes are using too many resources.
Volume usage status check (check-volume-status)
Checks whether the persistent volume claims associated with the deployment are running out of space.
Restriction: Only persistent volume claims that are mounted by a running pod are monitored.
Operator namespace status check (check-operator-namespace-status)
Checks whether the resources in the operators project for the deployment are healthy.
Important: If you also want to check the status of the operators in the project where the scheduling service is installed, you must run the apply-privileged-monitoring-service command with the --cluster_components_ns=${PROJECT_SCHEDULING_SERVICE} option.
EDB cluster status check (check-edb-cluster-status)
Checks whether any instances of EDB Postgres that are associated with the deployment are healthy. For example, whether the database that IBM Software Hub uses to store metadata for the deployment is healthy.
Options What to do
You did not install the privileged monitoring service, and you don't plan to install it
  1. Go to 10. Upgrading the admission controller webhook
You did not install the privileged monitoring service, but you plan to install it
  1. Complete Upgrading privileged monitors (Upgrading from Version 5.1 to Version 5.2).
  2. Go to 10. Upgrading the admission controller webhook
You installed the privileged monitoring service
  1. Complete Upgrading privileged monitors (Upgrading from Version 5.1 to Version 5.2).
  2. Go to 10. Upgrading the admission controller webhook

10. Upgrading the admission controller webhook

The configuration admission controller webhook enables services to use a shared set of custom certificates. If you installed the IBM Software Hub configuration admission controller webhook, a cluster administrator must upgrade the webhook after you upgrade IBM Software Hub.

User icon Cluster administrator When icon Repeat as needed

Services that support shared custom certificates
  • AI Factsheets
  • Analytics Engine powered by Apache Spark
  • Cognos Analytics
  • Data Privacy
  • DataStage
  • Data Virtualization
  • Db2 Big SQL
  • IBM Match 360
  • OpenPages
  • RStudio®
  • Watson Studio
  • Watson Studio Runtimes
  • watsonx Assistant
  • watsonx.data
  • watsonx Orchestrate
Options What to do
You did not install the admission controller webhook, and you don't plan to install it
  1. Go to 11. Completing post-upgrade tasks.
You did not install the admission controller webhook, but you plan to install it
  1. Complete Upgrading the IBM Software Hub configuration admission controller webhook (Upgrading from Version 5.1 to Version 5.2).
  2. Go to 11. Completing post-upgrade tasks.
You installed the admission controller webhook
  1. Complete Upgrading the IBM Software Hub configuration admission controller webhook (Upgrading from Version 5.1 to Version 5.2).
  2. Go to 11. Completing post-upgrade tasks.

11. Completing post-upgrade tasks

After you upgrade IBM Software Hub, determine whether there are any additional tasks that you should complete to configure your IBM Software Hub cluster.

User icon Instance administrator When icon Repeat as needed

Options What to do
You upgraded the services when you upgraded the platform
  1. Complete the appropriate tasks for your environment in Setting up services after install and upgrade.
You didn't upgrade the services when you upgraded the platform
  1. Upgrade the services in the instance. For more information, see Services.
  2. Complete the appropriate tasks for your environment in Setting up services after install and upgrade.