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:
  1. Log into your OpenShift cluster with your OpenShift user credentials:

    oc login
  2. 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
  3. 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.

  4. 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