Upgrade considerations on VMware

Before upgrading API Connect on VMware, ensure that your deployment meets all the upgrade requirements.


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

Restriction: A direct upgrade from any version of 10.0.1.x to API Connect or later is not supported. You must upgrade to 10.0.5.x as an interim step.
Upgrade from: How to upgrade to

    Versions and were skipped


    Version was skipped

Direct upgrade; see Upgrading to the latest version of 10.0.1.x-eus on VMware
Two upgrades required; see:
  1. Upgrading to on VMware
  2. Upgrading to the latest version of 10.0.1.x-eus on VMware
Direct upgrade supported; see Upgrading to the latest version of 10.0.1.x-eus on VMware
  • plus iFixes
  • plus iFixes
  • plus iFixes
Two upgrades required; see:
  1. Upgrading from or higher to on VMware
  2. Upgrading to the latest version of 10.0.1.x-eus on VMware
Upgrading to the latest version of 10.0.1.x requires a disaster-recovery process; see Upgrading from to the latest 10.0.1.x-eus on VMware
Not supported
  • 2018 FP24 and later
See Upgrading from 2018 to the latest 10.0.1.x-eus on VMware


  • The instructions for upgrading apply to the latest Fix Pack plus iFix version (if any). Ensure that you are upgrading to the latest Fix Pack version. For information on the latest Fix Pack, see What's New in the latest release.

  • Before starting the upgrade, verify that API Connection deployment is fully operational. See Checking cluster health on VMware.

    This step is optional because a health check will be run automatically as part of the apicup subsys install command. Note that you might still want to run the health check when preparing for the upgrade, to ensure the health of the backup image you must create prior to running apicup subsys install.

  • When upgrading API Connect, complete a manual backup of the management database and Portal subsystem just prior to starting the upgrade. Note that this backup is in addition to any scheduled backups that you have configured. The manual backup ensures that any data changes that occurred after the most recent scheduled backup are captured.

    For details on creating a backup, see Backing up the Management subsystem in a VMware environment and Backing up and restoring the Developer Portal in a VMware environment.

  • Ensure that port 9178 is open between the Analytics, Management, and Portal subsystems and the system running apicup.

    An i/o timeout error can occur if the firewall rejects traffic to the appliance. Make sure port 9178 is open and try again. Example error message:

    apicup subsys install test-analytics upgrade_analytics_lts_v10.0.1.0.tgz
    INFO[0000] Preparing update
    INFO[0010] Sending update packet to cluster (connected to testsrv0192.subnet1.example.com)
    Error: failed to install the subsystem: unable to open file send stream:  
     rpc error: code = Unavailable desc = all SubConns are in TransientFailure, 
     latest connection error: connection error: 
     desc = "transport: Error while dialing dial tcp i/o timeout"
  • If not already set up, send your deployment logs to a remote server. The upgrade process terminates pods, and the logs will be lost if not stored remotely. To send your deployment logs to a remote server, see Configuring remote logging for a VMware deployment.
  • Download the Install Assist (APICUP) installer from the same URL where you download your Fix Pack version. You must use the latest Install Assist package with the latest product version.
  • The original project directory created with the APICUP installer during the initial product installation (for example, myProject) is required to both restore the database and to upgrade your deployment. You cannot restore the database or perform an upgrade without the initial project directory because it contains pertinent information about the cluster. A good practice is to back up the original project directory to a location from which it can always be retrieved.
  • If the upgrade is initiated from the original project directory, the certificates are automatically copied into the upgraded version. The original project directory contains the apiconnect-up-v10.yml file. An upgrade using the same project directory as the one used for installation will transfer the encryption-secret and all other certificates for the project to the upgraded version.
  • All external traffic to the management server must be blocked during the upgrade of the management subsystem. This restriction applies to traffic from all sources via the user interfaces (Cloud Manager, API Manager), CLI, and REST API. The Cloud Manager and API Manager UIs cannot be used during the upgrade of the management subsystem. The Developer Portal also cannot be used to create, update, or delete any applications, subscriptions, memberships, or consumer organizations during the time
  • The upgrade order for subsystems is important. Upgrade the subsystems in the following order: (1) Management, (2) Portal (3) Analytics (4) Gateway. Management must be upgraded first. Gateway must be upgraded after Management because upgrading the Management service before the Gateway ensures that any new policies and capabilities will be available to a previously registered Gateway service.
  • When maintaining API Connect, do not use kubectl exec commands to access API Connect pods unless advised by IBM.

    Do not make any changes on the deployed VMs unless documented here or otherwise advised by IBM. Attempting to manually update packages, adding new users, or installing new software will likely cause problems. Operating system updates are handled by API Connect fix packs.

Disable Analytics data collection before upgrading

Temporarily stop the Analytics data collection to avoid losing event data during the upgrade. After the upgrade is complete, you can start Analytics data collection again.

Disable the Analytics message queue feature before upgrading

If you enabled the analytics message queue feature, you must disable it before upgrading. You can re-enable the message queue feature after the profile change is complete.

To disable the message queue:

  1. Edit the analytics-extra-value.yaml file.
  2. Locate the mq subsection and change the enabled setting to false.
          enabled: false
  3. Apply the change:
    apicup subsys install <subsystem_name>

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

From IBM® API Connect Version, 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 are parsable and 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 parsable 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
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:
  $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:
    type: object
    - name
        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.

x-ibm-gateway-cors-allow-credentials-when-no-cors-policy API property is deprecated

In v2018, when cross-origin resource sharing (CORS) is enabled for an API, every response to a CORS request contains the header:

Access-Control-Allow-Credentials: true

Inclusion of Access-Control-Allow-Credentials (ACAC) does not provide optimal security, so starting with v2018.4.1.17, an API property can be set to prevent this header from being returned:

Name: x-ibm-gateway-cors-allow-credentials-when-no-cors-policy
Collection: *
Value (string): off

The Collection setting refers to a specific Catalog to which a property value applies. The "*" value means the value applies to all catalogs. You can either specify * or a Catalog (collection) name.

The property can also be set by using the DataPower CLI:

api-definition myAPI
  property x-ibm-gateway-cors-allow-credentials-when-no-cors-policy * off

Important: The value of this property must be exactly the string off (case-sensitive) in order to remove the header.

It is only possible to turn off this header, or leave it on, for an entire API. In order to have more control, such as returning the header for some origins and not others, you must upgrade to version 10 and use the CORS policy feature. For more info, see:

In API Connect v10.0.1.4-ifix1-eus or later, the x-ibm-gateway-cors-allow-credentials-when-no-cors-policy property works, but only for API definitions which do NOT contain a cors-policy. You cannot define both this property and a CORS Policy on the same API definition.

This property is deprecated in version 10: a warning will be written to the log for every CORS request received by an API whose definition contains this property.

For version 10, the recommended way to ensure the ACAC header does not appear in CORS responses is to add a CORS policy to the API definition. In version 10, any API definition which has a cors-policy defined will NOT return the ACAC header by default . Note that it is possible in the CORS policy rules to explicitly return the ACAC header for some or all origins.

If you move your configuration from 2018 to or later, and have this custom property defined in your API definitions, you will not see any change in behavior, other than new warnings in the log. This property will remove the ACAC header for any API definition where it appears.

If, when you move your configuration from 2018 to version 10, you want to have the ACAC header present in the CORS responses, you can leave the API definitions as-is (without the new property defined) and the ACAC header will be returned, as long as a cors-policy is not added to the API definition. Note also that even with a CORS policy defined for an API, the ACAC header can be returned if desired by explicitly allowing it in the rules of the CORS policy.

Note that the x-ibm-gateway-cors-allow-credentials-when-no-cors-policy property in an API definition:

  • Will cause a commit-time error in version 10 if a cors-policy is also present in the same API definition
  • Will NOT work in version 10 or version 2018 to turn ON the ACAC header; it can ONLY be used to turn OFF the header. Explanation:
    • In 2018, ACAC is on by default
    • In 10, without cors-policy, ACAC is on by default
    • In 10, with cors-policy, ACAC can be turned on for specific origins via rules in cors-policy