Upgrading API management

Upgrade the API management component (API Connect) in IBM Cloud Pak® for Integration from version 2020.3 to 2020.4.1, or upgrade to the newest version of API Connect used in 2020.4.1.

About this task

Table 1 lists the highest (newest) operator version for each version of API Connect (the operand).

Table 1. API Connect versions and operators
API Connect version Operator channel version Highest operator version
10.0.1.4-ifix1-eus v2.1.4-eus 2.1.5
10.0.1.2-ifix2-eus v2.1-eus 2.1.3
10.0.1.2-ifix1-eus v2.1-eus 2.1.2
10.0.1.2-eus v2.1-eus 2.1.1
10.0.1.1-eus v2.1-eus 2.1.0
10.0.1.0 v2.0 2.0.0
10.0.0.0-ifix2 v1.0 1.0.2

The upgrade procedure depends on your current version of IBM Cloud Pak for Integration:

Note: Upgrading from API Connect V2018 (Cloud Pak for Integration 2020.2 or earlier) requires a manual upgrade of the API Connect deployment as explained in Upgrading from v2018 FP13-ifix1 on Cloud Pak for Integration, in the API Connect documentation.

Upgrading the deployed version of API Connect to 10.0.1.4-ifix1-eus

Upgrade the API Connect component in CP4I from v10.0.1.1-eus or later to 10.0.1.4-ifix1-eus.

Before you begin

If you are running API Connect v10.0.1.2-eus, your deployment might be experiencing DNS errors in pgbouncer. Review the known issue to determine whether your deployment is affected and if so, to replace the pgbouncer image before upgrading to API Connect 10.0.1.4-ifix1-eus.

Known issue: Pgbouncer DNS error in v10.0.1.2-eus

Complete the following steps to determine whether your deployment is experiencing DNS errors with pgbouncer, and to replace the pgbouncer image if needed. This issue only affects API Connect v10.0.1.2-eus. If you are running a different version of 10.0.1.x-eus, your deployment is not affected and you can proceed directly to the upgrade steps.

Determine whether your v10.0.1.2-eus deployment is experiencing the problem:
  1. Get the pgbouncer pod name:
    oc get pods -n <APIC_namespace> | grep 'pgbouncer'

    where <APIC_namespace> is the namespace where you installed API Connect.

  2. Check the pgbouncer log for the server DNS lookup failed error message:
    oc logs <pgbouncer-pod-name> -n <APIC_namespace> | grep 'server DNS lookup failed'
If the server DNS lookup failed message appears in the log, then your deployment is impacted and you must replace the pgbouncer image. If other errors appear, this procedure will not correct them and you should contact IBM Support for assistance. If no errors appear, you can proceed directly to the upgrade steps.
Replace the pgbouncer image:
  1. Get the new pgbouncer image format from the registry where v10.0.1.2-ifix2 images were pushed; for example:
    <registry-name>/ibm-apiconnect-management-crunchy-pgbouncer@sha256:4a5caaf4e5cd4056ccb3de7d39b8e343b0c4ebce7cae694ccbfbe80924d98752

    For CP4I, the default registry-name is icr.

  2. Get the pgbouncer deployment name:
    oc get deploy -n <APIC_namespace> | grep 'pgbouncer'
  3. Edit the pgbouncer deployment:
    oc edit deploy <pgbouncer-deploy-name> -n <APIC_namespace>
  4. In the deployment, replace the container image section with the new image that you downloaded.

  5. Wait for the pgbouncer pod to restart.

  6. Exec into the pgbouncer pod:
    oc exec -it <pgbouncer-pod> -n <APIC_namespace> -- bash
  7. Execute pgbouncer --version and make sure the response matches the following information:
    bash-4.4$ pgbouncer --version
    PgBouncer 1.15.0
    libevent 2.1.8-stable
    adns: evdns2
    tls: OpenSSL 1.1.1g FIPS  21 Apr 2020
    systemd: yes
  8. Verify that the server DNS lookup failed no longer appears in the pgbouncer log:
    oc logs <pgbouncer-pod-name> -n <APIC_namespace> | grep 'server DNS lookup failed'
  9. Delete back-end microservices to force a restart:
    1. Get the apim microservices pod name: oc get pods -n <APIC_namespace> | grep 'apim'
    2. Delete the apim pod: oc delete pod <apim-pod> -n <APIC_namespace>
    3. Get the lur microservices pod name: oc get pods -n <APIC_namespace> | grep 'lur'
    4. Delete the lur pod: oc delete pod <lur-pod> -n <APIC_namespace>
    5. Get the task manager microservice pod name: oc get pods -n <APIC_namespace> | grep 'task'
    6. Delete the task manager pod: oc delete pod <task-manager-pod> -n <APIC_namespace>

  10. Make sure the deployment is up and running before proceeding to upgrade to 10.0.1.4-ifix1-eus.

About this task

If you already deployed the API management capability for 2020.4.1 using API Connect 10.0.1.1-eus or later, you can upgrade to 10.0.1.4-ifix1-eus by completing the following steps.

Procedure

  1. Patch the pgcluster resource:

    This step applies to all versions of API Connect 10.0.1.x. You must complete this step before attempting an upgrade.

    1. Run the following command to find the pgcluster name:
      oc -n <APIC_namespace> get pgcluster
    2. Run the following command to patch the pgcluster:
      oc -n <APIC_namespace> patch pgcluster <pg-cluster-name> --type=json -p='[{'op': 'remove', 'path': '/spec/pgDataSource'}]'
  2. Upgrade the OpenShift cluster to 4.6.16 or later as explained in Upgrading Red Hat OpenShift.
    • Change the channel in OpenShift to 4.6, and wait for the upgrade to finish.
    • Wait for nodes to all show Kubernetes 1.19.x
  3. If you use the Operations Dashboard with API management, complete the following steps to upgrade the dashboard and the corresponding images used in API management:
    1. Upgrade the Operations Dashboard.
    2. Update the image paths in the API Connect Cluster CR's spec.gateway.openTracing section as explained in step 2 of Enabling open tracing for API management. The paths provided in the instructions are valid for the new release.
  4. Update the operator channels by completing the following steps:
    Attention: Upgrade the DataPower operator before upgrading the API Connect operator, to ensure that dependencies are satisfied.
    1. Update the DataPower operator channel to 1.2-eus.
      • If you enabled Automatic subscriptions previously, the operator version will automatically upgrade to 1.2.2 if it is not at that level already.
      • If you enabled Manual subscriptions previously, and if operator channel is already on 1.2-eus, OpenShift UI (OLM) will notify you that an upgrade is available. You must manually approve the upgrade. (Does not apply to fresh install).

      Wait for the operator to update, for the pods to restart, and for a Ready status.

      Note: There is a known issue on OpenShift 4.6.7 or higher that can cause the DataPower operator v1.2.0 to fail to start. If the operator fails to start, uninstall the DataPower operator and update to DataPower operator v1.2.1 or later. Version 1.2.1 (or later) of the operator fixes the limitation, and will start.
    2. Update the API Connect operator channel to 2.1-eus.
      • If you enabled Automatic subscriptions previously, the Operator version will auto upgrade to 2.1.5, if it is not at that level already.
      • If you enabled Manual subscriptions previously, and if operator channel is already on 2.1-eus, OpenShift UI (OLM) will notify you that an upgrade is available. You must manually approve the upgrade. (Does not apply to fresh install).

      Wait for the operator to update, for the pods to restart, and for a Ready status.

  5. Verify that the IBM API Connect capability displays Succeeded (green check mark) in Platform Navigator.

    Do not proceed until you see the Succeeded status.

  6. Update the operands:
    1. In the Platform Navigator, click the Runtimes tab.
    2. Click Menu icon at the end of the current row, and then click Change version.
    3. Click Select a new channel or version, and then select 10.0.1.4-ifix1-eus in the Channel field.

      Selecting the new channel ensures that both DataPower Gateway and API Connect are upgraded.

    4. Click Save to save your selections and start the upgrade.

      In the runtimes table, the Status column for the runtime displays the "Upgrading" message. The upgrade is complete when the Status is "Ready" and the Version displays the new version number.

Upgrading API management from CP4I 2020.3 to CP4I 2020.4.1

About this task

Upgrading to 2020.4.1 requires you to update the version of OCP to 4.6.x or later, then update IBM Cloud® Platform Common Services, Platform Navigator, and API Connect to the eus subscription channel. When you upgrade the IBM Cloud Pak for Integration API management capability to release 2020.4.1, you deploy the newest version of API Connect.

Procedure

Complete the steps in the following sequence:

  1. Upgrade OCP to 4.6.latest.

    Do not proceed to the next step until all Kubernetes nodes show that they are updated to version 1.19.x.

  2. Use the OCP UI to upgrade the common services operator by changing the subscription channel to the eus version.
  3. Use the OCP UI to upgrade the Platform Navigator operator by changing the subscription channel to the eus version.
  4. If you use the Operations Dashboard with API management, complete the following steps to upgrade the dashboard and the corresponding images used in API management:
    1. Upgrade the Operations Dashboard.
    2. Update the image paths in the API Connect Cluster CR's spec.gateway.openTracing section as explained in step 4 of Enabling open tracing for API management.
  5. Use the OCP UI to upgrade the DataPower operator by changing the subscription channel to the eus version.
  6. Use the OCP UI to upgrade the API Connect operator by changing the subscription channel to the eus version.
    Notes:
    • After the operators are upgraded, the following status condition displays for API Connect on the Platform Navigator UI:

      Product version 10.0.1.0-627 is not compatible with your current platform.

      This is a temporary condition because you have not completed the upgrade yet. You can ignore this message.

    • If you upgrade from API Connect V10.0.1.0 directly to V10.0.1.x on OpenShift, you will encounter a known problem with the API Connect operator. During the upgrade, the API Connect operator will be stuck in the "Upgrade available" state as shown in the following image:
      API Connect continues to display the "Upgrade available" message

      In addition, the catalog-operator in the OLM namespace will throw the following error:

      sync "<namespace>" failed: found more than one head for channel

      You can work around the error by completing the following steps:

      This workaround will not have a downtime impact.
      1. Delete the following operators: DataPower operator, IBM Cloud Platform Common Services, and ibm-apiconnect operator.
      2. Re-install the ibm-apiconnect operator.
  7. Use Platform Navigator to complete the upgrade for API Connect and DataPower by changing the subscription channel to the 10.0.1.4-ifix1-eus version.

    DataPower is deployed as a component of API Connect, so when you set the channel for API Connect, DataPower is automatically upgraded as well.

    Note: While you navigate in Platform Navigator to complete this step, the following message might display:

    Minor issue deploying stack-name. Product version 10.0.1.0-627 is not compatible with your current platform.

    This is another temporary message indicating that you have not completed the upgrade yet, and you can ignore it. If the message appears again after you dismiss it, continue dismissing it.

    1. In the Platform Navigator, click the Runtimes tab.

      If an update is available for a runtime, the Information icon displays next to the runtime's current Version number.

      Attention: Verify that the Status displays "Ready" before attempting an update.
    2. Click Menu icon at the end of the current row, and then click Change version.
    3. Click Select a new channel or version, and then select 10.0.1.4-ifix1-eus in the Channel field.

      Selecting the new channel ensures that both DataPower Gateway and API Connect are upgraded.

    4. Click Save to save your selections and start the upgrade.

      In the runtimes table, the Status column for the runtime displays the "Upgrading" message. The upgrade is complete when the Status is "Ready" and the Version displays the new version number.