Upgrading instances

Instances in IBM Cloud Pak® for Integration can be upgraded in the Platform UI or the CLI.

Before you begin

Review Upgrading from 2022.2 or Upgrading from 2023.4 before you upgrade an instance. Pay attention to the required order of all upgrades tasks for Cloud Pak for Integration.

Important: Because the upgrade process does not automatically migrate users from the previous identity and access management system to Keycloak, you need to recreate 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. If you upgraded the Platform UI, Keycloak was installed automatically. If you are not currently using the Platform UI, you can install it now to trigger an automatic installation of Keycloak. To install, see Deploying the Platform UI. The compute resources of the Platform UI are minimal, but if you don't want to install it, you can manually trigger installation of Keycloak by following the steps in Installing the identity and access management system when the Platform UI is not installed.

Important: Upgrade all instances of API management, if using, to the 16.1.0 version. Complete the upgrade of all API management instances before upgrading any gateway instances (IBM DataPower Gateway). For more information, see Upgrading API management.

This task must be performed by an administrator. For more information, see Cloud Pak for Integration roles and permissions (if using the Platform UI), or OpenShift Roles and permissions (if using the CLI).

Upgrading by using the Platform UI

Complete the steps under "Upgrading instances" in Managing versions and upgrades by using the Platform UI to upgrade instances by using the Platform UI.

Upgrading by using the CLI

Note: After the operator is upgraded, the most efficient way to upgrade your instances is to regenerate the upgrade plan to get updated guidance. An upgrade plan contains CLI commands you can copy and run to upgrade each instance in your Cloud Pak for Integration installation. Using the CLI commands that are returned in the upgrade plan helps you avoid the error-prone process of manually editing each instance and figuring out what values to change on every single instance. For more information, see Upgrading from 2022.2 or Upgrading from 2023.4.

If you choose not to generate an upgrade plan to guide the upgrade of your instances by using the CLI, follow these steps:

Log into your cluster with your OpenShift user credentials:
```
oc login
```
Get the list of instances that are running on the cluster you want to upgrade. For the value of <custom-resource-kind> that corresponds to your instance type, see the table at the end of this section:
```
oc get <custom-resource-kind> --all-namespaces
```
For example:
```
oc get Dashboard
```
Identify the instance you want to upgrade so that you can edit the custom resource:
```
oc edit <custom-resource-kind> <instance-name>
```
For example:
```
oc edit Dashboard db-01-quickstart
```
This opens the custom resource in your default editor.

Enter values for the following:
- spec.version - the instance version to which you want to upgrade. Find the corresponding instance version for a given instance type fin Operator and instance versions for this release.
  
  Users can also identify what versions are available for a given instance by reviewing the status.versions.available section of the custom resource object.
- spec.license.license - After you identify the version to which you want to upgrade, you might need to also update the license.
  
  Find the version to which you want to upgrade in the status.versions.available section of the custom resource. The licenses that are compatible with each version are also listed there. You can use any license that has matchesCurrentType: true.
  
  For example, in the Dashboard custom resource, the following section specifies that the L-UAZF-8ZYQDD license is compatible with the 12.0.10 instance channel, and it has matchesCurrentType: true:
```
- name: 12.0.10
  licenses:
    - displayName: IBM App Connect Enterprise 12.0.10.0
      link: https://www.ibm.com/support/customer/csol/terms/?id=L-UAZF-8ZYQDD
      matchesCurrentType: true
      name: L-UAZF-8ZYQDD
```
  For more information about specific licenses, see Licensing.
Save your changes. The instance begins upgrading.
Get the list of instances that are running on your cluster so that you can track the status of the upgrade.
```
oc get <custom-resource-kind> --all-namespaces
```
For example:
```
oc get Dashboard --all-namespaces
```

Custom resource kinds for each instance type

Instance type	Custom resource kind
Platform UI	`PlatformNavigator`
Automation assets	`AssetRepository`
Assembly	`IntegrationAssembly`
API management	`APIConnectCluster`
Event Manager	`EventEndpointManagement`
Event Gateway	`EventGateway`
Integration dashboard	`Dashboard`
Integration design	`DesignerAuthoring`
Integration runtime	`IntegrationRuntime`
Queue manager	`QueueManager`
Messaging server	`MessagingServer`
Messaging queue	`MessagingQueue`
Messaging channel	`MessagingChannel`
Messaging user	`MessagingUser`
Kafka cluster	`EventStreams`
Enterprise gateway	`DataPowerService`
High-speed transfer server	`IbmAsperaHsts`

Additional information

To get additional information on upgrading each instance type, see the following documentation.

Platform UI: See Upgrading the Platform UI.
API management: See Upgrading API management.
Integration dashboard, Integration design, and Integration runtime: See the IBM App Connect documentation: Upgrading or migrating from previous releases.
Event Manager: See the IBM Event Endpoint Management documentation: Upgrading.
Event Gateway: See the IBM Event Endpoint Management documentation: Upgrading.
Kafka cluster: See the IBM Event Streams documentation: Upgrading.
High-speed transfer server: See Upgrading High-Speed Transfer Server.
Queue manager: See the IBM MQ documentation: Upgrading the IBM MQ Operator and queue managers.