Upgrading from 2023.2

Upgrade IBM Cloud Pak® for Integration from version 2023.2 to version 2023.4 by generating an upgrade plan.

Important: Upgrading to version 2023.4 requires that your installation is already at version 2022.2 or 2023.2. If upgrading from an earlier version, upgrade to 2022.2 or 2023.2 first. For instructions, go to the Upgrading page and select the procedure for the version from which you are upgrading.

To upgrade, you must be a cluster administrator. For more information, see OpenShift Roles and permissions.

Important: Upgrading to 2023.4 removes the Grafana instance that is installed by Cloud Pak foundational services. For more information on this and other product changes, see the What's new in IBM Cloud Pak for Integration 2023.4.1.

Generating an upgrade plan

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

Important: Upgrading Cloud Pak for Integration installs the new identity and access management system. The upgrade process does not automatically migrate users from the previous identity and access management system to Keycloak, so you must re-create users during the upgrade in the "Configuring the new identity and access management system" step. For more information, see Identity and access management.

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

Applying the correct fix pack for the 2023.2 release.
Upgrading OpenShift to 4.12. For more information, see Upgrading Red Hat OpenShift.
Installing the IBM Cloud Pak for Integration operator.
Installing the certificate manager.
Upgrading the catalog sources and mirroring images for the 2023.4 release.
Upgrading the operators. For more information, see Upgrading operators.
Upgrading Cloud Pak foundational services. For more information, see Upgrading IBM Cloud Pak foundational services.
Upgrading the Platform UI. For more information, see Upgrading the Platform UI.
Configuring the new identity and access management system.
Upgrading the instances. For more information, see Upgrading instances.
Upgrading OpenShift beyond 4.12 (optional). For more information, see Upgrading Red Hat OpenShift.
Cleaning up Cloud Pak foundational services resources. For more information, see Cleaning up Cloud Pak foundational services resources.

Important: To ensure a successful upgrade, complete all tasks in the order that is provided by the upgrade plan. After you complete each upgrade step, regenerate the upgrade plan to get updated guidance and to validate that you can proceed to the next step.

Generating an upgrade plan by using the CLI

Log in to the Red Hat OpenShift CLI.
```
oc login
```
Set the OPERATOR_NAMESPACE variable. For <namespace>, enter the namespace where the operators are installed. When installing in All namespaces on the cluster mode, this namespace will be openshift-operators:
```
export OPERATOR_NAMESPACE=<namespace>
```
For example:
```
export OPERATOR_NAMESPACE=openshift-operators
```

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

docker run --platform linux/amd64 --pull=always \
  -it -v ${KUBECONFIG:-~/.kube/config}:/kube/config \
  --env KUBECONFIG=/kube/config icr.io/cpopen/ibm-integration-upgrade-must-gather:v3 \
  --namespace ${OPERATOR_NAMESPACE} \
  --to 2023.4 \
  --debug

If you have installed operators in A specific namespace on the cluster mode, go back to the previous step and set the OPERATOR_NAMESPACE variable to the namespace for any other A specific namespace on the cluster installation in this cluster. Repeat the command as needed.
After you complete each upgrade step, regenerate the upgrade plan to get updated guidance and validate that you can proceed to the next step.

Generating an upgrade plan by using the Platform UI

Follow the steps in the "Generating an upgrade plan" section of Managing versions and upgrades by using the Platform UI to generate an upgrade plan.

Applying the correct fix pack of the 2023.2 release that supports the upgrade process

Apply the correct fix pack of the 2023.2 release that supports the upgrade process. The upgrade plan tells you what the required fix packs are and whether the Cloud Pak for Integration installation meets the requirements. For more information on applying 2023.2 fix packs, see Applying fix packs between major releases.

Installing the IBM Cloud Pak for Integration operator

If your current installation of Cloud Pak for Integration does not have the IBM Cloud Pak for Integration operator, and you use any instance type that uses IBM Cloud Pak foundational services identity and access management, you must install the operator. Follow the procedure in Installing the operators by using the Red Hat OpenShift console to install it.

The upgrade plan confirms whether or not you need to install the operator.

Installing the certificate manager

If you are using API management, install the appropriate certificate manager:

If you are installing on OpenShift 4.12 on s390x (IBM Z®) or ppc64le (IBM® POWER®) hardware, install the latest version of the IBM Cert Manager operator.
If you are installing on OpenShift 4.12 on other hardware, or on OpenShift 4.14 on any hardware, install the cert-manager Operator for Red Hat OpenShift, in the cert-manager-operator namespace (project). For more information, see Installing the cert-manager Operator for Red Hat OpenShift.

Upgrading the catalog sources and mirroring images for the 2023.4 release

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.
If you are not using the IBM Operator Catalog (some online installations and all air-gapped installations), update the catalog sources and images for the 2023.4 release. Complete all steps in Applying fix packs between major releases that are applicable for your environment.

When the catalog sources and images are updated with the latest 2023.4 content, you can proceed with the upgrade.

Configuring the new identity and access management system

The upgrade process does not automatically migrate users from the previous identity and access management system to Keycloak. You need to migrate users yourself during upgrade. If this is not done before upgrading instances, users might lose access to those instances until the new identity and access management system is configured.

So that user migration can occur, use one of the following methods for triggering Keycloak installation:

If you already have the Platform UI deployed, simply upgrade it when prompted by the upgrade plan. The Platform UI triggers the installation of Keycloak automatically during upgrade.
Deploy the Platform UI (if you do not currently have it) when the upgrade plan prompts you to upgrade users. The compute resources of the Platform UI are minimal. The Platform UI automatically triggers the installation of Keycloak when you upgrade Cloud Pak for Integration by using the upgrade plan in Upgrading from 2023.2 or Upgrading from 2022.2. For more information, see Deploying the Platform UI.
You can also manually initiate the installation of Keycloak. For more information, see Installing the identity and access management system when the Platform UI is not installed.

For information on migrating your identity and access management configuration, see Migrating users from IAM to Keycloak.

Important: If you are using API management (IBM API Connect), make sure that the usernames from the identity provider that is used with the previous identity and access management system are preserved correctly when configuring Keycloak. For more information, see the documentation for configuring each type of identity provider in the Identity and access management section.

Parent topic:

Upgrading