Upgrading from 2021.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 2021.4 release

• Patching operators and capabilities with the 2021.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.

If you have an online installation and are using the IBM Operator Catalog, no action is needed for this task, because the IBM Operator Catalog polls every 45 minutes.

If you are not using the IBM Operator Catalog (some online installations and all air-gapped installations), you must patch the latest 2021.4 catalog sources and images on the cluster:

• Go to the section for Adding catalog sources to an air-gapped OpenShift cluster. Follow all tasks in the procedure that are applicable for your environment (whether bastion host, portable compute device, or portable storage device) to update the catalog sources and images for the 2021.4 patch release.

After the catalog sources and images have been updated, apply the most recent patches to the 2021.4 operators and instances with the 2021.4 fixpack.

When upgrading from 2021.4, all the installed Cloud Pak for Integration instances must first be patched with a 2021.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. Upgrade the operators with the fixpack versions for 2021.4 that allow this upgrade path. Do not upgrade operators beyond the operator channels in the following table; they must remain in the 2021.4 channel.

2. Confirm that all operators satisfy the minimum patch versions listed in the 2021.4 fixpack version column.

   Operator name	Operator channel	2021.4 fixpack version
   IBM Cloud Pak for Integration	v5.3	5.3.2
   IBM Automation Foundation assets	v1.4	1.4.5
   IBM Cloud Pak for Integration Operations Dashboard	v2.5	2.5.6
   IBM API Connect	v2.3	2.3.0
   IBM MQ	v1.8	1.8.2
   IBM Event Streams	v2.5	2.5.2
   IBM App Connect	v4.0	4.0.0
   IBM DataPower Gateway	v1.5	1.5.2
   IBM Aspera HSTS	v1.4	1.4.1

3. Upgrade the instances of all the capabilities to the latest fixpack versions for 2021.4 that allow this upgrade path.

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

   • For detailed instructions on updating instances of specific capabilities, review Upgrading capabilities. For a list of fixpacks, consult Operator channel versions for IBM Cloud Pak for Integration releases.

   • You can upgrade the instances by using the Platform UI (formerly Platform Navigator) or the CLI.

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

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

• 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 are applicable for your environment (whether bastion host, portable compute device, or portable storage device).

After the catalog sources and images have been updated for the 2022.2 release, you can proceed with the upgrade tasks.

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

Now upgrade OpenShift 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.

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 of Upgrading the Platform UI.

2. Wait until the status of the Platform UI instance changes to 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) to the 2022.2 version, if used. This must be done before upgrading any instances of the gateway 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 are upgraded, the upgrade to Cloud Pak for Integration 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 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.

The IBM Automation Foundation Core operator can be uninstalled after upgrade is complete if there are no Cartridge objects left in the scope of the operator:

• If the Cloud Pak for Integration operators are installed in the All namespaces on the cluster installation mode, confirm there are no Cartridge objects remaining anywhere on the cluster before uninstalling.

• If the Cloud Pak for Integration operators are installed in the A specific namespace on the cluster installation mode, you only need to confirm there are no Cartridge objects in the specific namespace. To find out the installation mode for the operators:

1. Log into the OpenShift web console.

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

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

4. In the list of installed operators, in the column for Managed Namespaces, if the entry is:

   • "All Namespaces", the installation mode is All namespaces on the cluster.

   • The name of a given project, such as test-namespace, the installation mode is A specific namespace on the cluster.

If there are no Cartridge objects left in scope, you can uninstall the operator. It is no longer needed to by Cloud Pak for Integration.

1. Click Operators > Installed Operators. Click to expand Project and select the project in which you installed the Cloud Pak for Integration operator. Find IBM Automation foundation Core.

2. Click the options for this operator, and click Uninstall operator.

3. Confirm the action, and the operator will be removed from the Installed Operators view.