Upgrading from 2020.4

An upgrade plan guides you through the upgrade of your Cloud Pak for Integration installation to a target version. Begin the upgrade process by generating an upgrade plan using the CLI or the Platform UI.

When the process is complete, you get a sequence of tasks (the upgrade plan) that are required for upgrading the Cloud Pak for Integration installation to 2022.2. These can include:

• Patching catalog sources and images for the 2020.4 release

• Patching operators and capabilities with the 2020.4 fixpack

• Patching catalog sources and images for the 2022.2 release

• Upgrading dependencies

• Upgrading Red Hat OpenShift Container Platform

• Upgrading the operators

• Upgrading the capabilities

• Cleanup

Generating an upgrade plan using the CLI

1. Log in to the OpenShift CLI.

2. Set the CP4I_NAMESPACE variable. For <namespace>, enter the namespace where the Platform UI is installed:

   export CP4I_NAMESPACE=<namespace>

   For example:

   export CP4I_NAMESPACE=integration

3. Start a local image. The following docker command runs a check of the specific Cloud Pak for Integration installation and compares the current installed versions of components with those that are part of the target version.

   docker run --pull=always \
     -it -v ${KUBECONFIG:-~/.kube/config}:/kube/config \
     --env KUBECONFIG=/kube/config icr.io/cpopen/ibm-integration-upgrade-must-gather:v2 \
     --namespace ${CP4I_NAMESPACE} \
     --to 2022.2 \
     --debug

4. If you have multiple instances of the Platform UI in the same cluster, set the CP4I_NAMESPACE variable in step 4 to the namespace for another instance and repeat the step as needed.

5. After you complete each upgrade step, regenerate the upgrade plan to get updated guidance and validate that you can proceed to the next step.

The first step for upgrade is to patch the 2020.4 catalog sources and images on the cluster:

• If you have an online installation and are using the IBM Operator Catalog, you can skip this section, because the IBM Operator Catalog polls every 45 minutes. To confirm:

  1. Log in to the OpenShift web console as an admininistrator.

  2. In the navigation menu, click Home > Search.

  3. Click the Resources tab, then search for and click CatalogSource.

  4. If ibm-operator-catalog is available in the list, then the IBM Operator Catalog is in use.

• If you are not using the IBM Operator Catalog (some online installations and all air-gapped installations), follow the procedure in Installing in an air-gapped environment to update the catalog sources and images for the 2020.4 patch release.

After the catalog sources and images have been updated with the latest 2020.4 patch, you can proceed with upgrading the 2020.4 operators and instances with the latest patches.

When upgrading from 2020.4, all the installed Cloud Pak for Integration capabilities must first be patched with a 2020.4 fixpack which allows the Cloud Pak to tolerate the upgrade to Red Hat OpenShift Container Platform 4.10 and Cloud Pak foundational services 3.19.

Before you begin: If you have the "Install all Cloud Pak for Integration Operators" operator (ibm-cp-integration) installed, uninstall it:

1. Log into your OpenShift cluster.

2. In the navigation menu, click Operators > Installed Operators.

3. For Project, select the namespace where the Cloud Pak for Integration operators are installed.

4. Click the 3-dot menu icon for Install all Cloud Pak for Integration Operators and click Uninstall Operator.

To patch the operators and capabilities:

1. Validate that all operators are at the operator channel and 2020.4 fixpack version listed in the following table, and if they are not, update as needed.

   Important: Do not upgrade operators beyond the listed operator channel.

   1. Log in to the OpenShift web console as an admininistrator.

   2. In the navigation menu, click Operators > Installed Operators.

   3. Click the operator name in the list.

   4. Click the Subscription tab.

   5. If the version listed for Channel needs to be updated, click the pencil (edit) icon. Select the new version and click Save. The operator version in the Installed Version field should now be in sync with the 2020.4 fixpack version.

   Operator name	Operator channel	2020.4 fixpack version
   IBM Cloud Pak for Integration Platform Navigator	v4.1-eus	4.1.8
   IBM Asset Repository (Automation assets)	v1.1-eus	1.1.7
   IBM Cloud Pak for Integration Operations Dashboard	v2.1-eus	2.1.11
   IBM API Connect	v2.1.6-eus	2.1.10
   IBM MQ	v1.3-eus	1.3.5
   IBM Event Streams	v2.2-eus	2.2.6
   IBM App Connect	v1.1-eus	1.1.10
   IBM DataPower Gateway	v1.2-eus	1.2.10
   IBM Aspera HSTS	v1.2-eus	1.2.2

2. Validate that all instances are at the minimum patch versions listed in the 2020.4 fixpack version column in the following table, and update them if they are not.

   • For detailed instructions on updating instances of specific capabilities, review Upgrading components in the 2020.4 documentation.

   • For a list of fixpacks, consult Operator channel versions for IBM Cloud Pak for Integration 2020.4.
     

     Important: Important: Apply only those fixpacks that are available to the current spec.version for a given instance of the 2020.4 release.

   To update the version using the Platform UI:

   1. In the OpenShift web console navigation menu, click Operators > Installed Operators.

   2. For Project, select the namespace in which Cloud Pak for Integration is installed; if you don't know it, select all projects.

   3. Search for and click IBM Cloud Pak for Integration Platform Navigator in the list.

   4. Click the Platform Navigator tab, then click an instance in the list (integration-navigator).

   5. In the Endpoints section, click an instance for Platform Navigator UI. The Platform UI welcome page opens.

   6. Click either the Capabilities or Runtimes tab to locate a capability instance.

   7. If the value in the Version column needs to be updated, hover over that capability in the list, click the 3-dot menu, and click Change version.

   8. Select the new channel version and click Change version.

   Capability name	2020.4 fixpack version
   Platform UI (Platform Navigator)	2020.4.1-8-eus
   Asset Repository (Automation assets)	2020.4.1-7-eus
   Integration tracing	2020.4.1-11-eus
   API management	10.0.1.*
   Messaging	9.2.0.5-r3-eus
   Event streams	10.2.1-eus
   Integration dashboard	11.0.0.18-r1-eus
   Integration designer	11.0.0.18-r1-eus
   Gateway	10.0.1.8-eus
   High speed transfer server	4.1.1-r1-eus

When all operators and instances are updated with the fixpack patch releases, you can proceed with the next section.

• If you have an online installation and are using the IBM Operator Catalog, you can skip this step, because the IBM Operator Catalog polls every 45 minutes. To confirm:

  1. Log in to the OpenShift web console as an admininistrator.

  2. In the navigation menu, click Home > Search.

  3. Click the Resources tab, then search for and click CatalogSource.

  4. If ibm-operator-catalog is available in the list, then the IBM Operator Catalog is in use.

• If you are not using the IBM Operator Catalog (some online installations and all air-gapped installations), you must update the catalog sources and images for the 2022.2 release: Go to the section for Mirroring images for an air-gapped cluster. Follow all tasks in the procedure that is applicable for your environment (whether bastion host, portable compute device, or portable storage device).

  After the catalog sources and images have been updated with the latest 2022.2 content, you can proceed with the upgrade.

The next step is to upgrade the Cloud Pak for Integration dependencies:

Upgrade OpenShift 4.6 to version 4.10 by following the procedure in Upgrading Red Hat OpenShift, unless you are running your cluster on managed OpenShift. In that case, refer to your managed service provider's documentation for OpenShift upgrades.

Note that when upgrading from Cloud Pak for Integration 2020.4, some instances may return a warning message similar to the following:

An EUS instance [2020.4.1-8-eus] has been installed but the OCP version [4.10.17] does not qualify for the extended support duration. This instance is supported as per a regular CD release.

The instance is in fact ready and working; this is a transient warning while upgrading to version 2022.2.

Once the dependencies and OpenShift are upgraded, upgrade the operators to the channels that are part of the 2022.2 release. You can upgrade directly to the 2022.2 channels; there is no need to go through each intermediate channel unless you are upgrading the IBM Event Streams operator. In that case, you must change the subscription channel to v3.0 before optionally upgrading to channel v3.1.

Once all the operators being used are upgraded to the 2022.2 channels, you can upgrade the capabilities.

Once all the operators are upgraded, upgrade your instances of capabilities (for example, API management or messaging) following this order:

1. Upgrade the Platform UI (previously the Platform Navigator) instance to the 2022.2 version by following the "Upgrading the Platform UI instance" section in Upgrading the Platform UI.

2. Wait until the Platform UI instance is Ready before upgrading any other capabilities.

3. Upgrade the integration tracing capability (Operations Dashboard operator), if used. This must be done before upgrading any instances that it is tracing. To do so, follow the instructions in Upgrading Integration tracing.

4. Upgrade all instances of the API management capability (IBM API Connect operator), if used, to the 2022.2 version. This must be done before upgrading any instances of the gataway capability (DataPower Gateway). For detailed instructions, see Upgrading API management.

5. Upgrade the other instances of capabilities to 2022.2 versions. For detailed instructions, see Upgrading capabilities.

Once all capabilities have been upgraded, the upgrade process to 2022.2 is complete.

Upgrade OpenShift to version 4.12 after the upgrade to Cloud Pak for Integration 2022.2 is complete.

To upgrade OpenShift, confirm that the latest available fix packs for the 2022.2 release are applied, then follow the instructions in Upgrading Red Hat OpenShift.

You also have the option to upgrade OpenShift to version 4.14 or 4.16 after the 4.12 upgrade is complete.

If you have an online installation from a previous release, and you are using the IBM Operator Catalog, use the procedure in Moving to specific catalog sources for each operator to move to specific catalog sources for each operator.

After the upgrade is complete, there are a few optional cleanup steps to perform:

1. If you previously installed the metering service, it is still available, but it will not receive future updates. If you confirm this service is no longer needed, uninstall by following the procedure in Uninstalling the metering service.

2. Monitoring now relies on the OpenShift monitoring stack. If you configured OpenShift monitoring in a previous version of Cloud Pak for Integration, you do not need to upgrade this service to continue using it. To move to OpenShift monitoring, follow the procedure in Upgrading the monitoring stack.