Upgrade from v2018: overview and considerations

Review the upgrade overview, requirements, and limitations before upgrading your API Connect 2018 deployment to v10 on VMware.

Overview of upgrade procedure

The upgrade from v2018 to the latest release of v10 is a fresh install of the v10 subsystems, followed by restoration of saved 2018 data and configuration.

For the management subsystem, you will use custom scripts to extract management database configuration from 2018, and then load it onto a fresh install of v10. The scripts complete the necessary conversion of the Management database information from Cassandra format to Postgres format. The scripts are provided as part of the latest API Connect 10 distribution files on Fix Central.

For the Developer Portal, you will perform a fresh install of the subsystem and then restore data from the 2018 backups.

For Analytics, you will perform a fresh install of the subsystem but you cannot restore data from the 2018 backups due to changes in the v10 Analytics subsystem.

When all subsystem upgrades are complete, you can upgrade DataPower Gateway.

Gateways can continue to run during this process so API traffic is not impacted.

Summary of the upgrade task flow:

  1. On the 2018 deployment:
    1. Backup each 2018 subsystem.
    2. For the management subsystem, use the provided script to extract the 2018 database.
    3. Power off the 2018 cluster.
  2. On a new v10 installation:
    1. Create a new v10 cluster using the 2018 project directory, the v10 installation utility (apicup) and the v10 distribution images (.ova).
    2. Install the management subystem. Start the v10 system using the newly created ISO.
    3. Use a provided script to load the extracted v2018 database info into the new v10 database.
    4. Install the Developer Portal subsystem and run a restore to load the 2018 backup data.
    5. Install the Analytics subsystem and run a restore to load the 2018 backup data.
    6. Upgrade the DataPower Gateway.

Planning a v10 deployment

Before you move from 2018 to v10, plan your v10 deployment by reviewing requirements and features:

Required backups of 2018 subsystems

Subsystems on 2018 must be backed up in the following order:

  1. Management subsystem
  2. Developer Portal subsystem
  3. Analytics subsystem

Ensure that your archives are valid.

Note: You cannot use a VMware snapshot to skip the preparation steps for the upgrade. VMware snapshots do not provide the necessary API Connect data and backups in a form that can be applied to a new API Connect v10 deployment in a VM.

Required disk space for extraction of 2018 management subsystem data

The upgrade from 2018 to v10 includes extraction of management database data. Prior to running the extract job, ensure that your virtual machine has sufficient disk space to hold a file containing this data.

The amount of disk space required scales with the amount of data on your system. As a minimum, ensure you have 3 times the size of the backup file for your 2018 Cassandra database.

To locate the backup file for your 2018 Cassandra database, see Step 3 in Restoring the management database in a Kubernetes environment.

Automatic shortening of subsystem names with greater than 63 characters

Version 10 imposes a length restriction of 63 characters for subsystem names. Version 2018 did not impose the restriction. If your v2018 subsystem names are greater than 63 characters in length, you must shorten them prior to upgrading. If you do not shorten them, the upgrade will programmatically shorten them for you. You will then want to check apiconnect-up-v10.yaml to determine the new shortened name.

The new value is found in spec.subsystems[n].metadata.name. For example, for a management subsystem, see the name: abcde-management entry below:

apiVersion: v1
kind: apic.ibm.com/APIConnectCluster
metadata:
  creationTimestamp: "2021-03-04T13:52:50Z"
  name: abcde
spec:
  secret-name: abcde-my-secret
  subsystems:
  - apiVersion: v1
    kind: apic.ibm.com/ManagementSubsystem
    metadata:
      creationTimestamp: "2021-03-04T13:52:50Z"
      name: abcde-management
    spec:
      ApplianceProperties:
        data-device: sdb

Upgrade Limitations

The upgrade is designed to bring your 2018 configuration and data onto a new v10 deployment. Note the following limitations:

  • The location of the v10 backups for the management subsystem must be different from the location of the 2018 backups of the management subsystem. Note that for v10, the management database changes from Cassandra to Postgres, so a new backup configuration is required.
  • The upgrade does not capture customizations to your 2018 configuration that you made with an extra-values file. If you created an extra-values file on 2018, you must modify it for the v10 deployment, as follows:
  • Version 10.0.5.0 and later use a new version of the Analytics subsystem, which has the following impacts on your upgrade process:
    • If you want to preserve your v2018 analytics data, export it to a backup location before upgrading as explained in Preparing the 2018 deployment for upgrade.
    • Disable analytics before upgrading as explained in Preparing the 2018 deployment for upgrade.
    • During the upgrade, the v2018 Analytics subsystem cannot work with v10 Management subsystem, so you must upgrade the new Analytics subsystem immediately. If there is an upgrade failure with Analytics, resolve it as soon as possible and run the upgrade again.

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

In 2018, 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 2018.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
exit

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 v10 and use the CORS policy feature. For more info, see:

In API Connect 10.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 v10: 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 10.0.1.4-ifix1-eus 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 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 10 or 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

Getting started with the upgrade procedure

The first task in the upgrade procedure is to prepare your 2018 deployment for upgrade. To get started, go to Preparing the 2018 deployment for upgrade