Upgrade considerations on OpenShift

Review the supported upgrade paths and other upgrade considerations on OpenShift or Cloud Pak for Integration.

Tip: After upgrade, clear your browser cache, and open a new browser window. This action avoids stale cache issues in your browser, that can result in unexpected behavior in the Cloud Manager and API Manager UIs.

Supported upgrade paths

Attention: API Connect 10.0.5.x is not supported on a FIPS-enabled environment.

Table 1 lists the releases of IBM® API Connect v10 that can be upgraded to the newest version.

Table 1. Supported upgrade paths on OpenShift
Upgrade from: How to upgrade to 10.0.5.8
  • 10.0.5.7
  • 10.0.5.6
  • 10.0.5.5
  • 10.0.5.4
  • 10.0.5.3
  • 10.0.5.2
  • 10.0.5.1
  • 10.0.5.0
  • 10.0.4.0-ifix3
  • 10.0.1.15-eus
  • 10.0.1.12-eus
  • 10.0.1.11-eus
  • 10.0.1.9-eus
  • 10.0.1.8-eus
  • 10.0.1.7-eus
Complete the procedure in Upgrading on OpenShift and Cloud Pak for Integration in this documentation.
Older versions of 10.0.x:
  • 10.0.4.0-ifix2
  • 10.0.4.0-ifix1
  • 10.0.4.0
  • 10.0.3.0-ifix1
  • 10.0.3.0
  • 10.0.2.0
Complete 2 upgrades:
  1. First, upgrade to 10.0.4-ifix3 as explained in Upgrading on OpenShift and Cloud Pak for Integration in the API Connect 10.0.4 documentation.

  2. Then, upgrade to 10.0.5.8 as explained in Upgrading on OpenShift and Cloud Pak for Integration in this documentation.
Older versions of 10.0.1.x:
  • 10.0.1.6-ifix1-eus
  • 10.0.1.6-eus
  • 10.0.1.5-ifix4-eus
  • 10.0.1.5-ifix3-eus
  • 10.0.1.5-eus
  • 10.0.1.4-ifix1-eus
  • 10.0.1.4-eus
  • 10.0.1.2-ifix2-eus
  • 10.0.1.2-ifix1-eus
  • 10.0.1.2-eus
Complete 2 upgrades:
  1. First, upgrade to 10.0.1.8-eus as explained in Upgrading to 10.0.1.8-eus online in the API Connect 10.0.1.x-eus documentation.

    You do not need to upgrade to a higher version of 10.0.1.x-eus because you can move directly from 10.0.1.8-eus to 10.0.5.8.

  2. Then, upgrade to 10.0.5.8 as explained in Upgrading on OpenShift and Cloud Pak for Integration in this documentation.
  • 10.0.1.1
  • 10.0.1.0
  • 10.0.0.0-ifix2
Complete 3 upgrades:
  1. First, upgrade to 10.0.1.2-ifix2-eus as explained in Upgrading on OpenShift and Cloud Pak for Integration in the API Connect 10.0.1.x-eus documentation.
    Note: Be sure to use the 10.0.1.2-ifix2-eus version of the operator channel, operator, and if applicable, case, as noted in the Operator, operand, and CASE version topic.
  2. Then, upgrade to 10.0.1.8-eus as explained in Upgrading to 10.0.1.8-eus online in the API Connect 10.0.1.x-eus documentation. You do not need to upgrade to a higher version because you can move directly from 10.0.1.8-eus to 10.0.5.8.

  3. Finally, upgrade to 10.0.5.8 as explained in Upgrading on OpenShift and Cloud Pak for Integration in this documentation.
2018 FP24 Complete 2 upgrades:
  1. First, upgrade to 10.0.5.4 as explained in Upgrading from 2018 to 10.0.5.4 on OpenShift.
  2. Then, upgrade to 10.0.5.8 as explained in Preparing to upgrade on OpenShift.

For upgrades to older fix packs, see Upgrading to older fix packs on OpenShift.

For information on the operator, operand, and CASE version used with each API Connect release, see Operator, operand, and CASE versions.

Supported DataPower Gateway versions

You can use any combination of API Connect 10.0.5.x with DataPower Gateway 10.5.0.x or DataPower API Gateway 10.5.0.x.

However, before you install, best practice is to review the latest compatibility support for your version of API Connect. To view compatibility support, follow the instructions in IBM API Connect Version 10 software product compatibility requirements to access API Connect information on the Software Product Compatibility Reports website. Once you access information for your version of API Connect, select Supported Software > Integration Middleware, and view the list of compatible DataPower Gateway versions.

Attention: Different releases of API Connect support different versions of OpenShift, so you might need to upgrade OpenShift after upgrading API Connect. For more information, see IBM API Connect Version 10 software product compatibility requirements.

OAuth provider resources with api.securityDefintions

Upgrades to V10.0.5.7. If you have native OAuth providers that are configured with the api.securityDefintions field assigned, then upgrade fails. Before upgrade, remove all api.securityDefintions from all native OAuth providers that you configured in the Cloud Manager and API Manager UIs: Switch to the source view and delete any securityDefintions sections that are present.

Exporting analytics data before upgrading to 10.0.5.0 or later

If upgrading from v10.0.4-ifix3, or upgrading from v10.0.1.7-eus (or higher): Upgrading to 10.0.5.x from an earlier version will result in the deletion of existing analytics data. If you want to retain your analytics data then you must export it before starting the upgrade. For instructions on exporting data, see the following API Connect documentation:

Upgrading multiple instances of API Connect

  • If a single operator manages multiple instances, all of those instances must be upgraded, one at a time, as soon as possible.

    The operator should not be managing an operand based on an older version any longer than necessary.

  • Ensure that each instance is fully upgraded before starting the upgrade on the next instance.

API transactions might fail during the upgrade of gateway pods.

Consider scheduling the upgrade during off-hours to avoid transaction failures.

When you upgrade a cluster of gateway pods in Kubernetes, a small number of API transactions may fail. During the upgrade, Kubernetes removes the pod from the load balancer configuration, deletes the pod, and then starts a new pod. The steps are repeated for each pod. Socket hang ups occur on transactions that are in process at the time the pod is deleted.

The number of transactions that fail depends on the rate of incoming transactions and the length of time needed to complete each transaction. Typically the number of failures is a very small percentage. This behavior is expected during an upgrade. If the failure level is not acceptable, schedule the upgrade during an off-hours maintenance window.

Note also that DataPower Gateway supports long-lived connections such as such as GraphQL subscriptions or other websockets connections. These long-lived connections might not be preserved when upgrading. Workloads with long-lived connections are more vulnerable to failed API transactions during upgrading.

You can limit the number of failed API transactions during the upgrade by using the DataPower Operator's lifecycle property to configure the preStop container lifecycle hook on the gateway pods. This approach mitigates the risk of API failures during the rolling update of the gateway StatefulSet by sleeping the pod for a span of time, allowing in-flight transactions to complete prior to the SIGTERM being delivered to the container. While this feature does not guarantee that no in-flight APIs would fail, it does provide some mitigation for in-flight transactions that can complete successfully within the configured time window. For more information, see Delaying SIGTERM with preStop in the DataPower documentation.

Upgrading to v10.0.5.3 (or later) from an earlier 10.05.x release.

Additional features related to inter-subsystem communication were added in v10.0.5.3. To enable and configure these features see: Optional post-upgrade steps for upgrade to 10.0.5.3 from earlier 10.0.5 release.

What to do next

Proceed to Preparing to upgrade on OpenShift to prepare your deployment for upgrading.