Upgrade overview and requirements

Overview of upgrade procedure

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

For the management subsystem, you will use custom scripts to extract management database configuration from v2018, 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 API Connect v10.0.1.2 (with latest iFix) distribution files on Fix Central.

For the Developer Portal and the Analytics subsystem, you will do a fresh install of the subsystem and then restore data from the v2018 backups.

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 v2018 deployment:
   1. Backup each v2018 subsystem.
   2. For the management subsystem, use the provided script to extract the v2018 database.
   3. Power off the v2018 cluster.
2. On a new v10 installation:
   1. Create a new v10 cluster using the v2018 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 v2018 backup data.
   5. Install the Analytics subsystem and run a restore to load the v2018 backup data.
   6. Upgrade the DataPower Gateway.

Planning a v10 deployment

• IBM API Connect Version 10 software product compatibility requirements
• Requirements for initial deployment on VMware
• Planning your deployment
• What's New in the latest release and What's new for v10 installation.
• Version 10 known limitations

Supported versions for upgrade from v2018

Required backups of v2018 subsystems

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

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

Ensure that your archives are valid.

Required disk space for extraction of v2018 management subsystem data

The upgrade from v2018 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 v2018 Cassandra database.

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

Upgrade Limitations

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

• 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 not succeed, and you will have to shorten them and repeat the upgrade.

  If you need to shorten subsystem names, you can follow specific instructions for each subsystem. Subsystem upgrade instructions are contained in Upgrading v2018 subsystems to v10.

  If your neglect to shorten subsystem names, the command:

  apicup subsys health-check <subsystem_name>

  will not return successfully after the upgrade. Error output may include:

  expect member mysystem0215.subnet.example.com 'Subsystem install required' to be 'false'(actual: true)

  1. To determine if the problem is caused by long subsystems, ssh to any one of the subsystem nodes and run sudo apic status.
  2. Look for output similar to:

     
     ...
        Subsystem detail: Error from server (ManagementCluster.management.apiconnect.ibm.com 
        "m8t-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" is invalid: 
        metadata.name: Invalid value: "m8t-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx": 
        CR name must not exceed 63 characters in length): 
        error when creating "/var/lib/apiconnect/subsystem/manifests/28.m8t-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-cr.yaml": 
        admission webhook "vmanagementcluster.kb.io" denied the request: ManagementCluster.management.apiconnect.ibm.com 
        "m8t-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" is invalid: metadata.name: 
        Invalid value: "m8t-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx": CR name must not exceed 63 characters in length

• The location of the v10 backups for the management subsystem must be different than the location of the v2018 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 v2018 configuration that you made with an extra-values file. If you created an extra-values file on v2018, you must recreate it on the v10 deployment.

  Note that the upgrade process uses a temporary extra-values file to configure upgrade settings, and then removes the temporary file upon successful completion of the upgrade. You can then recreate your extra-values file

• Analytics data may be lost during the time between the shutdown of the v2018 deployment and the start of the new v10 deployment.

  Optionally, you can stop the collection of v2018 Analytics data and write to disk any data that is currently in the pipeline. When data collection is stopped, the Analytics subsystem stops acknowledging requests from the gateway, and relies on the buffer there to avoid losing data. See the procedure in Stopping Analytics data collection.

Getting started with the upgrade procedure

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