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.

You must be a Cloud Pak for Integration administrator to upgrade instances. For more information, see Cloud Pak 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 OpenShift cluster with your OpenShift user credentials:
```
oc login
```
Get the list of instances that are running on the OpenShift 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 OpenShift 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 Connect cluster	`APIConnectCluster`
Event Manager	`EventEndpointManagement`
Event Gateway	`EventGateway`
Event Processing	`EventProcessing`
Flink	`FlinkDeployment`
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`
Kafka topic	`KafkaTopic`
Kafka user	`KafkaUser`
Kafka Connect runtime	`KafkaConnect`
Kafka connector	`KafkaConnector`
Enterprise gateway	`DataPowerService`
High-speed transfer server	`IbmAsperaHsts`

Additional information

While the previous instructions should address your needs around upgrading instances, you can get additional information about specific instance types in the following topics.

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