Multi-node upgrade example (upgrades from 7.3.x or 7.4.x)

This topic provides a detailed example of how to upgrade an earlier API Gateway version (in this case, 7.4.1) to API Gateway 7.6.2 in a multi-node domain.

Tip   You can use the steps in this example as a guide when upgrading a multi-node domain from API Gateway 7.3.x or 7.4.x to 7.6.2. However, you must remember to modify the steps appropriately for your version and topology.

The following diagram shows an example flow for a multi-node upgrade.

Sample flow for multi-node upgrade

The sysupgrade script includes validation features to guide you through the steps. We recommend that you use the status command to help keep track of the steps on each node.

sysupgrade does not change the old API Gateway installation. You can always revert back to using the old API Gateway installation.

Sample API Gateway topology

In this example, API Gateway 7.4.1 has a three-node topology that includes two Admin Node Managers (on NodeA and NodeC), and one Node Manager (on NodeB). A single API Gateway instance runs on each node. There are two API Gateway groups as follows:

  • GatewayGroup has an API Gateway instance running on NodeA and NodeB.
  • GatewayManagerGroup has a single API Manager-enabled API Gateway instance running on NodeC.

The example topology is shown in the following diagram:

Example multi-node topology

API Gateway NodeA

This node runs an Admin Node Manager and a single API Gateway named APIGateway1 in a group named GatewayGroup.

API Gateway NodeB

This node runs a Node Manager and a single API Gateway named APIGateway2 in a group named GatewayGroup.

API Manager-enabled NodeC

This node runs an Admin Node Manager and a single API Manager-enabled API Gateway named APIManagerGateway in a group named GatewayManagerGroup.

Step 1 – Check the old installation on each node

Perform the checks on your old API Gateway 7.4.1 installation, as detailed in Checklist for the old API Gateway installation.

Note   The sample topology requires Apache Cassandra. If your topology does not use Apache Cassandra, and you do not wish to install or use Apache Cassandra in your new installation, you must also perform the checks detailed in Checklist for upgrades without Apache Cassandra.

Step 2 – Install API Gateway 7.6.2 on each node

On each node in the multi-node topology where your old API Gateway domain is running, you must install API Gateway 7.6.2.

Perform the following steps:

  1. Select the Custom option in the installer, and select the following components:
    • Admin Node Manager – You must select this on NodeA, NodeB and NodeC for the sample topology.
    • API Gateway Server – You must select this on NodeA, NodeB and NodeC for the sample topology. If you are installing on a node that does not run any API Gateways (running an Admin Node Manager only), you do not need to select this.
    • Policy Studio– Select this on the nodes on which you will run Policy Studio.
    • API Manager– You must select this on NodeC for the sample topology. You can also select it on other nodes if required.
    • Cassandra – Select this only on the nodes on which you want to install an Apache Cassandra database on the local machine alongside API Gateway.
    • Do not select Cassandra if you want to install an Apache Cassandra database on a remote machine (on a different host from API Gateway).
    • The sample topology requires Apache Cassandra, so you must set up a Cassandra cluster with only one node for upgrade. You must not enable Cassandra authentication on this node. For more details, see Configure an Apache Cassandra database cluster in the new installation.
    • For more details on Apache Cassandra, see Install an Apache Cassandra database in the API Gateway Installation Guide.
  2. Do not select:
    • QuickStart tutorial.
    • The QuickStart tutorial creates and starts processes in the new installation. sysupgrade requires that no processes are running in the new installation.
  3. When prompted for an installation directory, ensure that you enter a new directory (for example, /opt/Axway-7.6.2). A warning message displays if you try to install 7.6.2 in the same directory as the old installation.
  4. When prompted to set an administrator user name and password, enter the same Admin Node Manager credentials that you use for the old API Gateway installation.
Tip   For more information on installation, including installation prerequisites and how to run the installer in unattended mode, see the API Gateway Installation Guide.

Step 3 – Check the new installation on each node

When the installation of API Gateway 7.6.2 is complete, perform the new installation checks detailed in Checklist for the new API Gateway 7.6.2 installation.

Step 4 – Run export and upgrade on each node

You must run the export and upgrade commands on each node before you can apply the upgrade to the new 7.6.2 system using the apply command. You can run and rerun these commands on NodeA, NodeB, and NodeC in any node order.

Identify which Admin Node Manager to specify to export

The sample topology has two Admin Node Managers (running on NodeA and NodeC). Because there are multiple Admin Node Managers, you must specify which Admin Node Manager to use for export with the --anm_host option, and this Admin Node Manager must also be the first node you upgrade. We recommend that you specify the first Admin Node Manager. For more information, see Which is the first Admin Node Manager?

This example upgrades NodeA first, so you must specify this node using the --anm_host option when running export on all nodes. The value of --anm_host must be an exact match of the host name in the topology (--anm_host NodeA in this case) and you must specify the same --anm_host on all nodes.

Run export and upgrade

Complete the following steps:

  1. Ensure that the old API Gateway processes are running on all nodes. This includes, for example, all Admin Node Managers, Node Managers, and API Gateway instances. These processes must be running in the old installation on all nodes to export the API Gateway configuration data.
  2. On each node, run the export and upgrade commands:
  3. Change to the upgrade/bin directory in the new installation, for example:
> cd /opt/Axway-7.6.2/apigateway/upgrade/bin
  1. Export the data from the old installation, for example:
> ./sysupgrade export --old_install_dir /opt/Axway-7.4.1/apigateway/ --anm_host NodeA
Note   The commands are exactly the same on each node. You must specify --anm_host Node A as a parameter to the export command on NodeA, NodeB, and NodeC.
  1. If any issues are identified during export, resolve them and rerun export if required.
  2. Finally, validate and upgrade the exported data.
  3. The sample topology uses Apache Cassandra to store API Manager data, and you must specify the host name or IP address of the new external Cassandra database cluster to the upgrade command. For example:
> ./sysupgrade upgrade --cass_host NodeA
  1. For more information, see Update your Apache Cassandra database connection details.
Note   If you are not using Apache Cassandra, run the upgrade command with the --no_cassandra option. For more information, see upgrade command options.

If there are any errors or warnings, you are prompted to examine the sysupgrade log files. For more details on errors and warnings that can occur during upgrade and recommended actions, see sysupgrade error reference. You can also use Policy Studio to resolve issues with the configuration. For more details, see Resolve upgrade issues in Policy Studio.

You must resolve any errors before proceeding. You can rerun export and upgrade multiple times until all issues are resolved.

Example export and upgrade errors and solutions

Before running export on NodeA, sysupgrade checks that the local Admin Node Manager and API Gateway are running and are the expected version. If these checks do not pass, sysupgrade generates errors and recommended solutions. For example:

  • If the Admin Node Manager is not running:
ERROR: Cannot connect to Admin Node Manager on localhost to retrieve product version.
Please start version [7.4.1] of the Admin Node Manager on localhost.
  • If the API Gateway is not running:
ERROR: Cannot connect to API Gateway [APIGateway1] in Group [Group1] on localhost; it could be down, or a wrong version could be running.
Please start version [7.4.1] of local API Gateway [APIGateway1] in Group [Group1] on localhost.
  • If the Admin Node Manager is running, but it is not the right version:
ERROR: Admin Node Manager on localhost is running version [7.3.1], but version [7.4.1] is required at this point.
Please stop version [7.3.1] of Admin Node Manager on localhost.
Please start version [7.4.1] of Admin Node Manager on localhost.

Before running export on NodeB, sysupgrade checks that the remote Admin Node Manager on NodeA, and the local Node Manager and API Gateway on NodeB, are running and are the expected version. If these checks do not pass, sysupgrade generates errors, for example:

  • The wrong Admin Node Manager version on NodeA is running:
ERROR: Admin Node Manager on host [nodea] is running version [7.3.1], but version [7.4.1] is required at this point.
Please stop version [7.3.1] of Admin Node Manager on host [nodea].
Please start version [7.4.1] of Admin Node Manager on host [nodea].
  • Admin Node Manager on NodeA is not running:
ERROR: Cannot connect to remote Admin Node Manager on host [nodea].
ERROR: Could not connect to the Admin Node Manager.
  • Node Manager running on localhost and it is the wrong version, or not running:
ERROR: Cannot connect to Node Manager on localhost; it could be down, or a wrong version could be running.
Please start version [7.4.1] of Node Manager on localhost.

Step 5 – Run apply on the first Admin Node Manager (NodeA)

The export and upgrade steps have now run on all nodes in the topology. The first node on which apply runs must be an Admin Node Manager, and because there are multiple Admin Node Managers, you must specify which Admin Node Manager to use for apply with the --anm_host option. We recommend that you specify the same Admin Node Manager that you specified to the export command in Step 4 – Run export and upgrade on each node.

The sample topology has two Admin Node Managers running on NodeA and NodeC. This example runs apply on NodeA first, then NodeB and NodeC. In this case, you must specify --anm_host NodeA when running apply on all nodes. The --anm_host value must be an exact match of the host name in the topology and you must specify the same --anm_host on all nodes.

To run apply, perform the following steps:

  1. Shut down all the old API Gateway installation processes on NodeA, NodeB, and NodeC in the topology.
  2. If you are using Apache Cassandra, start Apache Cassandra on the host you specified to the upgrade command (for example, host NodeA). It must be started before running apply.
  3. In a multi-node domain, you must make the following changes in the CASSANDRA_HOME/conf/cassandra.yaml file before you can start Apache Cassandra:
    • seed provider, parameters, seeds: Default value is 127.0.0.1. Change this to the IP address or host name of the Cassandra host.
    • listen_address: Default value is localhost. Change this to IP address or host name of the Cassandra host.
    • rpc_address: Default value is localhost. Change this to IP address or host name of the Cassandra host.
  4. For more information on configuring and starting Cassandra, see Install an Apache Cassandra database in the API Gateway Installation Guide.
  5. Run the apply command on NodeA:
> cd /opt/Axway-7.6.2/apigateway/upgrade/bin
> ./sysupgrade apply --anm_host NodeA
  1. Before running apply on NodeA, sysupgrade checks that the local Admin Node Manager and API Gateway on NodeA are not running. If you failed to shut down these processes, the following warning appears:
Please stop the API Gateway [APIGateway1] in group [GatewayGroup] if it is still running (management port [8085] is in use)
Please stop the local Node Manager if it is still running (management port [8090] is in use)

The version 7.6.2 Admin Node Manager and API Gateway are now running on NodeA. You can launch the version 7.6.2 API Gateway Manager web console on https://NodeA:8090.

Step 6 – Run apply on the other nodes

You can now run apply on the other nodes. You must run apply on each of the other nodes in turn, and not in parallel.

First, run apply on NodeB. For example:

> cd /opt/Axway-7.6.2/apigateway/upgrade/bin
> ./sysupgrade apply --anm_host NodeA

Before running the apply step on NodeB, sysupgrade checks the remote Admin Node Manager on NodeA is running and is version 7.6.2. If this check fails, an error similar to the following appears:

ERROR: The remote Admin Node Manager on host [NodeA] is version [7.4.1], the required version is [7.6.2]
On the remote host [NodeA], please ensure that version [7.6.2] of the Admin Node Manager is running 

sysupgrade also checks that the local Node Manager and API Gateway on NodeB are not running, as shown in Step 5 – Run apply on the first Admin Node Manager (NodeA).

When apply completes on NodeB, run apply on NodeC. For example:

> cd /opt/Axway-7.6.2/apigateway/upgrade/bin
> ./sysupgrade apply --anm_host NodeA

sysupgrade is now complete on all nodes. All the API Gateway 7.6.2 processes are running on all nodes in the topology.

Step 7 – Verify the upgrade

Verify the upgrade as detailed in the single-node upgrade example – see Step 6 – Verify the upgrade.

For the sample topology you can also perform the following checks to verify the API Manager upgrade:

  1. Connect to the API Manager web console (for example, on https://HOST:8075/).
  2. Log in as an administrator user and view the organizations, application developers, and applications.
  3. Log in as a non-administrator user and view the applications.

For more details on API Manager, see the API Manager User Guide.

Related Links