Upgrade and migration overview

This topic introduces API Gateway upgrade and migration, and describes how to perform an upgrade of an API Gateway domain from an earlier version to API Gateway version 7.5.3. It also provides recommended best practices for test upgrades.

Note   Throughout this guide the term old installation is used to refer to the earlier version of API Gateway (the version being upgraded), while the term new installation is used to refer to the 7.5.3 version of API Gateway.

Upgrade and migration process

The upgrade and migration process involves exporting data from your old installation, upgrading the data, and applying the upgraded data to your new installation. Each step must complete successfully before you can proceed to the next step.

Note   After you have installed v7.5.3, ensure you have installed the latest available service pack before starting the upgrade.

Overview of upgrade process

 

API Gateway provides the sysupgrade command to upgrade your API Gateway system and migrate your data. This script provides feedback at each step, which enables you to resolve any issues before proceeding to the next step. This ensures that all possible issues are identified and resolved before you apply the upgraded data to your new installation.

Overview of upgrade steps

An upgrade always requires the following steps:

  1. Install API Gateway 7.5.3 in a new directory.
  2. Install the latest available service pack for v7.5.3.
  3. Export the data from the old installation.
  4. Validate and upgrade the data. Resolve any issues identified by the upgrade process before you proceed to the next step.
  5. Apply the upgraded data to the 7.5.3 installation.
  6. Verify that the upgrade completed successfully.

Upgrade commands

To perform an upgrade, you must always run the following sysupgrade commands in the following order:

Step Command Description
1 export Export data from the old API Gateway installation on the local node.
2 upgrade

Validate data exported from the old installation, and upgrade it to version 7.5.3. You can keep your old installation running during this step, so you can fix any issues reported in the logs without service interruption.

3 apply Create the new API Gateway processes on the local node, and import the upgraded data into the 7.5.3 installation.
Tip   You can also use the status command at any stage to see which commands have run, and which command will run next (see Utility commands).

For more details on performing an upgrade, see Upgrade from API Gateway 7.3.x or 7.4.x or Upgrade from API Gateway 7.5.x.

For a quick overview of the differences between upgrades from 7.3.x or 7.4.x and upgrades from 7.5.x, see Compare upgrades from 7.3.x or 7.4.x with upgrades from 7.5.x.

Utility commands

The sysupgrade script also provides utility commands. These optional commands can be useful when performing more complex upgrades:

Command Description
status Get the status of the sysupgrade process on the local node. For example, which commands have run (export, upgrade, or apply), and which command will run next. Running the status command is recommended before you run each command, especially in a multi-node upgrade where it is easy to lose track of what upgrade step or machine you are on.
clean Reset the new installation on the current node back to a factory installation. This enables you to restart the sysupgrade process.

For details on all commands and options, see sysupgrade command reference.

Compare upgrade paths

For a quick overview of the differences between upgrades from 7.3.x or 7.4.x and upgrades from 7.5.x, see Compare upgrades from 7.3.x or 7.4.x with upgrades from 7.5.x.

Best practices for test upgrades

To perform a test upgrade, run the export and upgrade commands on all nodes in your API Gateway domain. You can do this while the old API Gateway installation is still running, because the export and upgrade commands do not modify the old installation. This way you can identify and resolve any issues with the upgrade without any service interruption. For example:

  1. Run the export command on Node1.
  2. Run the upgrade command on Node1.
  3. Analyze the warnings and errors on Node1, and take any necessary actions. You must rerun export and upgrade after updating your configuration to resolve any warnings or errors. You might need to rerun export and upgrade multiple times on Node1 to ensure that all issues are resolved.
  4. Repeat steps 1, 2, and 3 for Node2, Node3, and so on, until all issues are resolved on all nodes.
  5. As long as apply has not been run on any node, you can rerun export and upgrade as many times as necessary without affecting other nodes. Rerunning export and upgrade on a node does not mean they must be rerun on other nodes in the system.

When you are happy with the results of the test upgrade on all nodes, you can shut down the old installation and apply the upgraded data to the new 7.5.3 installation. For example:

  1. Run the apply command on Node1, Node2, and so on, until the upgrade is complete.

For a detailed example of a multi-node upgrade from 7.3.x or 7.4.x, see Multi-node upgrade example (upgrades from 7.3.x or 7.4.x).

For a detailed example of a multi-node upgrade from 7.5.x, see Multi-node upgrade example (upgrades from 7.5.x).

Resolve upgrade errors and warnings

The export and upgrade commands identify issues in the configuration that might cause problems during the upgrade. Errors indicate problems that you must resolve before proceeding with an upgrade, while warnings indicate issues that might require action. By identifying and resolving issues at this stage, you can avoid unexpected issues when using the apply command to complete the upgrade. For more details on errors and warnings, see sysupgrade error reference.

Related Links