Upgrade considerations on native Kubernetes

Review the supported versions, requirements, and limitations for upgrading API Connect on Kubernetes.

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 Kubernetes
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 subsystems on native Kubernetes in this 10.0.5 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.0-ifix3 as explained in Upgrading subsystems on native Kubernetes in the API Connect 10.0.4 documentation.

  2. Then, upgrade to 10.0.5.8 as explained in Upgrading subsystems on native Kubernetes 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 on Kubernetes 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.

  2. Then, upgrade to 10.0.5.8 as explained in Upgrading subsystems on native Kubernetes 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-ifix1-eus as explained in Upgrading from v10 to v10.0.1.2 on Kubernetes in the API Connect 10.0.1.x-eus documentation.

  2. Next, upgrade to 10.0.1.8-eus as explained in Upgrading to 10.0.1.8-eus on Kubernetes 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.

  3. Then, upgrade to 10.0.5.8 as explained in Upgrading subsystems on native Kubernetes 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 Kubernetes.
  2. Then, upgrade to 10.0.5.8 as explained in Upgrading subsystems on native Kubernetes.

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

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 Kubernetes, so you might need to upgrade Kubernetes before 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.

Ensuring compatibility with Drupal 10 for Developer Portal customizations

Review the Guidelines on upgrading your Developer Portal from Drupal 9 to Drupal 10 to ensure that any customizations to the Developer Portal are compatible with Drupal 10.

In API Connect 10.0.5.3, the Developer Portal moved from Drupal 9 to Drupal 10 (this upgrade also requires PHP 8.1). The upgrade tooling will update your Developer Portal sites; however, if you have any custom modules or themes, it is your responsibility to ensure their compatibility with Drupal 10 and PHP 8.1 before starting the upgrade.

Note: If you are upgrading to 10.0.5.3 from 10.0.1.7 or earlier, or from 10.0.5.0 or earlier, your Developer Portal sites will first be upgraded to Drupal 9.5 and then to Drupal 10. When you are planning your the upgrade to 10.0.5.3, consider the extended time frame. To shorten your upgrade window, consider removing the Developer Portal sites that you do not need.

Exporting analytics data before upgrading from a version prior to 10.0.5.0

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 Additional considerations for upgrading analytics from a version prior to 10.0.5.0

Validating an API definition file with the API Dev Tools Swagger Parser

From IBM API Connect Version 10.0.3.0 or later, SwaggerDoc (OpenAPI 2.0) and OpenAPI 3.0 documents that form API definition files are now validated at stage or publish time by the API Dev Tools Swagger Parser. Before upgrading, you should ensure that your existing API definition files can be parsed and are considered valid by the Swagger Parser tool. Note that any API definitions that are already staged or published are not impacted, but would undergo Swagger Parser validation again should they be re-staged or re-published in the future.

You can use either of the following techniques to ensure that existing API definition files are can be parsed and considered valid by the Swagger Parser:
  • Download and install the swagger-parser-cli tool (see https://www.npmjs.com/package/swagger-cli). This tool includes a validate command that can validate local API definition files against the SwaggerDoc (OpenAPI 2.0) and OpenAPI 3.0 schemas, in both JSON and YAML formats.
  • Use the browser-based Swagger Parser Validator available at https://apitools.dev/swagger-parser/online/; this accepts a URL to existing files available online, or can accept text copied and pasted into the tool, in both JSON and YAML formats. It can likewise validate against the SwaggerDoc (OpenAPI 2.0) and OpenAPI 3.0 schemas.
Note: Staging or publishing an API in API Connect results in additional syntactic validation of IBM extensions to SwaggerDoc (OpenAPI 2.0) and OpenAPI 3.0, as well as semantic validation to make sure that policies and other resources that the API refers to are valid within the context of the staging or publishing operation. Any errors associated with this additional validation will not be caught by the local or online Swagger Parser tool, nor will they be caught by the apic validate toolkit CLI command.
The Swagger Parser tool will report an invalid OpenAPI document. For example, if a document is missing a mandatory section such as info or paths, the following error is reported:
[object Object] is not a valid Swagger API definition
If a required property is missing from a given section, a specific error is reported. For example, if the info section is missing the required version property, the following error is reported:
Swagger schema validation failed.
  Missing required property: version at #/info

JSON_OBJECT_VALIDATION_FAILED
Additionally, if the document contains any local references (that is, values of $ref properties) that do not resolve to an existing reference within the document (known as de-referencing), this is also be flagged as an error. For example, if a document contains the following as a reference:
schema:
  $ref: '#/definitions/Pet'
then the definition of Pet (that is, #/definitions/Pet) must exist in the same document, at the given path (definitions section in this example), similar to the following:
definitions:
  Pet:
    type: object
    required:
    - name
    properties:
      id:
        type: integer
        format: int64
If the local reference is not found within the document, the following de-referencing error is reported:
Token "Pet" does not exist.

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 (or later) from earlier 10.0.5 release.