Upgrade API Gateway on a Vordel OEL-based physical appliance

This topic describes how to upgrade from an Oracle Enterprise Linux (OEL) hardware appliance (Vordel appliance) to the Axway Appliance Platform, a SuSE Linux Enterprise hardware appliance, and migrate your data to API Gateway version 7.5.3.

Overview of the upgrade process

The API Gateway upgrade and migration process involves exporting data from your old API Gateway Appliance installation, upgrading the data, and applying the upgraded data to your new API Gateway 7.5.3 installation. Each step must complete successfully before you can proceed to the next step. API Gateway provides the sysupgrade command to upgrade your API Gateway system and migrate your data.

Overview of API Gateway appliance upgrade steps

For more information on the API Gateway upgrade process and the sysupgrade command, see Upgrade and migration in the API Gateway Upgrade Guide.

Usually, you use sysupgrade to upgrade an old API Gateway installation to API Gateway version 7.5.3 on the same set of machines that the old version was running on. However, you can run the export step on all nodes running the old version, manually copy the output data files to another set of machines, and then run the upgrade and apply steps on the new machines. This is the approach used for appliance upgrade and migration.

Using this approach requires you to make some manual changes to the exported files after you copy them to the new appliances, and before you run upgrade or apply. Additionally, you must shut down the old appliances after running the upgrade step and before running apply. This is necessary to avoid potential issues with both the old and new API Gateway processes accessing shared resources concurrently when the new API Gateway processes are started by the apply step.

Summary of steps for appliance upgrade

The following summarizes the steps to perform an appliance upgrade:

  1. Unpack and configure each of the new Axway Appliance Platform appliances.
  2. Install API Gateway 7.5.3 on each of the OEL appliances so that you can run sysupgrade export to export the data.
  3. Export the data from each of the OEL appliances:
    1. Run sysupgrade export on each OEL appliance.
    2. Copy the exported data to each corresponding new Axway Appliance Platform appliance.
    3. Update the host names and IP addresses in the exported data on each Axway Appliance Platform appliance.
  4. Migrate the OS level settings from each of the OEL appliances to the new Axway Appliance Platform appliances.
  5. Run sysupgrade upgrade to upgrade the exported data on each of the Axway Appliance Platform appliances.
  6. Apply the upgrade on each of the Axway Appliance Platform appliances:
    1. Shut down the OEL appliances.
    2. If you are using Apache Cassandra, start the Cassandra service on the new Axway Appliance Platform appliances.
    3. Run sysupgrade apply on the first Admin Node Manager.
    4. Run sysupgrade apply on the other nodes in turn.

Before you upgrade

You must complete the following steps before you upgrade:

Checklist for old version OEL appliances

  • Check if the IP address or host name of any of the appliances in the old version domain are explicitly used in:
    • Entity store configuration for any group, or custom Node Manager entity store configuration
    • envSettings.props files
    • API Manager configuration
    • KPS data
    • /etc/hosts files or other bespoke OS locations
  • You can modify any explicit IP addresses or host names in the copy of the exported data on the new appliance, before running the upgrade and apply commands. You do not need to modify the old version appliance.
  • Perform the checks detailed in Checklist for the old API Gateway installation in the API Gateway Upgrade Guide.
  • If you do not wish to use Apache Cassandra in your new installation, perform the checks detailed in Checklist for upgrades without Apache Cassandra in the API Gateway Upgrade Guide.

Checklist for new Axway Appliance Platform appliances

  • Check that the required API Gateway licenses are installed on the new appliances.
  • At a minimum, you must have a license for API Gateway server on your new appliances. Licenses are also required for the following components:
    • API Gateway Analytics
    • API Manager
  • In addition, you must have a McAfee license file to use the McAfee Anti-Virus filter, and you must have a FIPS-compliant mode license file to run API Gateway in FIPS-compliant mode.
  • The licenses must be installed in the conf/licenses directory of the API Gateway installation (for example, /opt/Axway-7.5.3/apigateway/conf/licenses).
  • Check that the new appliances have access to all of the external systems that the old appliances invoke, for example, external databases, LDAP directories, back-end services, and so on.
  • Perform the checks detailed in Checklist for the new API Gateway 7.5.3 installation in the API Gateway Upgrade Guide.

Multi-node upgrade example

This section provides a step-by-step example of a multi-node domain upgrade from OEL-based appliances to Axway Appliance Platform appliances.

Sample upgrade topology

The sample topology used in this example is as follows:

Sample topology for multi-node appliance upgrade

In this example the host names of the nodes are as follows:

Old OEL appliance nodes:

  • NodeA-old
  • NodeB-old
  • NodeC-old

New Axway Appliance Platform appliance nodes:

  • NodeA-new
  • NodeB-new
  • NodeC-new

Step 1 – Check the old installation on each OEL appliance node

Perform the checks detailed in Checklist for old version OEL appliances on each of your OEL appliances.

Step 2 – Install API Gateway 7.5.3 on each OEL appliance node

To enable you to run the sysupgrade export command on an OEL-based appliance, you must install API Gateway 7.5.3 on each of the OEL appliance nodes (for example, NodeA-old, NodeB-old, and NodeC-old).

Perform the following steps on each node:

  1. Download and run the API Gateway 7.5.3 installer. You can download the installation files for UNIX/Linux from Axway Support at https://support.axway.com.
  2. Select the Custom option in the installer, and select API Gateway Appliance server and the Admin Node Manager components.

Ensure that you specify a new directory for the 7.5.3 installation (for example, /opt/Axway-7.5.3).

When the installation is complete, proceed to the next step. Do not create or start any Node Managers, groups, or API Gateway Appliances in the new installation.

Tip   You can also run the installer in unattended mode. For more details, see the API Gateway Installation Guide.

Step 3 – Run export on each OEL appliance node

To export the data from the old API Gateway installation, you must run the sysupgrade export command on each of the OEL appliance nodes (for example, NodeA-old, NodeB-old, and NodeC-old).

Complete the following steps on each node:

  1. Change to the upgrade/bin directory in the new installation, for example:
> cd /opt/Axway-7.5.3/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-old

In this example, NodeA-old is the first Admin Node Manager and must be specified using the --anm_host option when running export on each node.

If any issues are identified during export, resolve them and rerun export if required.

For more details on running export for a multi-node domain see Multi-node upgrade example (upgrades from 7.3.x or 7.4.x) in the API Gateway Upgrade Guide.

Create tarball of exported data on each node

To enable you to copy the exported data from the OEL appliance nodes to the new Axway Appliance Platform nodes, you must create a tarball of the exported data on each of the OEL appliance nodes (for example, NodeA-old, NodeB-old, and NodeC-old).

For example, when the export step completes, the following directory will exist on NodeA-old:

/opt/Axway-7.5.3/apigateway/upgrade/bin/out/export

This directory contains a set of subdirectories (for example, activemq, cassandra, esgroups, topology, and so on).

To create a tarball from the contents of the export directory and its subdirectories, enter the following commands:

# cd /opt/Axway-7.5.3/apigateway/upgrade/bin/out
# tar cvfz node-a-export.tgz export/
Tip   Name the export tar file with a meaningful name that relates to the host name where the data was exported, or to the host name where the data is to be migrated.

Copy and extract exported data to each new node

To make the exported data available to the new Axway Appliance Platform nodes, you must copy the exported data from each of the OEL appliance nodes (for example, NodeA-old, NodeB-old, and NodeC-old) to the corresponding new Axway Appliance Platform node (for example, NodeA-new, NodeB-new, NodeC-new).

For example, transfer the node-a-export.tgz file from NodeA-old to a location on NodeA-new.

To copy and untar the node-a-export.tgz file to the directory /opt/Axway-7.5.3/apigateway/upgrade/bin/out on NodeA-new, enter the following commands:

# mkdir /opt/Axway-7.5.3/apigateway/upgrade/bin/out
# cd /opt/Axway-7.5.3/apigateway/upgrade/bin/out
# cp /some_location/node-a-export.tgz
# tar -xvf node-a-export.tgz

When the extraction completes, the following directory will exist on NodeA-new:

/opt/Axway-7.5.3/apigateway/upgrade/bin/out/export

Update host names and IP addresses in exported files on each new node

The exported data might contain references to host names or IP addresses of the OEL appliance nodes. Before you run the upgrade command, you must replace all occurrences of the OEL appliance host names and IP addresses with the new appliance host names and IP addresses.

Search and edit the exported files on each of the new Axway Appliance Platform nodes (for example, NodeA-new, NodeB-new, NodeC-new), as follows:

  1. Make a backup of the exported data in the /opt/Axway-7.5.3/apigateway/upgrade/bin/out/export directory.
  2. Search all *.xml, *.props, and *.json files in the /opt/Axway-7.5.3/apigateway/upgrade/bin/out/export directory for the host names or IP addresses of any of the OEL appliance nodes.
  3. Use a text editor to replace each occurrence with the corresponding host name or IP address of the new Axway Appliance Platform nodes.

Depending on your configuration, you might only need to update the topology.json file (for example, /opt/Axway-7.5.3/apigateway/upgrade/bin/out/export/topology/groups/topology.json):

Find the “hosts” section, for example:

…
 "hosts" : [ {
   "id" : "host-1",
   "name" : "NodeA-old.axway.com"
 }, {
   "id" : "host-2",
   "name" : "NodeB-old.axway.com"
 } , {
   "id" : "host-3",
   "name" : "NodeC-old.axway.com"
 }
],
…

Replace all occurrences of the old host names with the new host names as follows:

…
 "hosts" : [ {
   "id" : "host-1",
   "name" : "NodeA-new.axway.com"
 }, {
   "id" : "host-2",
   "name" : "NodeB-new.axway.com"
 } , {
   "id" : "host-3",
   "name" : "NodeC-new.axway.com"
 }
],
…
Note   Do not change the “id” values, change only the “name” values to match the new appliances.

Step 4 – Migrate the OS level settings

To migrate the Operating System configuration from each of the OEL appliance nodes, you must manually copy the settings in the Web Administration Interface to the new Axway Appliance Platform nodes.

Caution   Several configuration items were hardened for increased security in the API Gateway Appliance 7.5.1 release. Take extra care if you are making changes to the settings in any of the following in the Web Administration Interface, as changing these settings might introduce a security risk:
  • IP Access Control
  • Linux Firewall
  • User Access Control
  • System Logs NG
  • Bootup and Shutdown

Do not make changes to these settings if you do not understand the impact.

To migrate the OS configuration settings, follow these steps:

  1. Log in to the Web Administration Interface (for example, https://APPLIANCE_IP_ADDRESS:10000). For more information on connecting to the Web Administration Interface, see Connect to consoles and user interfaces.
  2. In the Web Administration Interface, click System Information to view the system information and status.

Example of appliance system information

  1. Verify that the operating system and appliance version are compatible with the migration before you proceed.
  2. Copy the settings on each Web Administration Interface page from the OEL appliance and re-enter the settings on the new Axway Appliance Platform appliance. Ensure that you save the settings in the Web Administration Interface on the new appliance. Additionally, some settings do not take effect until the appliance is rebooted (for example, Routing and Gateways on the Network Configuration page).
  3. This manual process can take a few minutes to several hours, depending on the level of customizations you have configured on your appliance. The quickest way to copy the settings is to use two monitors side by side, one connected to the Web Administration Interface on the old OEL appliance and the other connected to the Web Administration Interface on the new appliance. In this way you can read the settings from each page on the OEL appliance and re-enter them on the corresponding page on the new appliance.

Step 5 – Check the new installation on each Axway Appliance Platform node

Perform the checks detailed in Checklist for new Axway Appliance Platform appliances on each of your new appliances.

Step 6 – Run upgrade on each Axway Appliance Platform node

To upgrade the data from the old API Gateway installation, you must run the sysupgrade upgrade command on each of the new Axway Appliance Platform nodes (for example, NodeA-new, NodeB-new, and NodeC-new).

Complete the following steps on each node:

  1. Change to the upgrade/bin directory in the new installation, for example:
> cd /opt/Axway-7.5.3/apigateway/upgrade/bin
  1. Upgrade the data from the old installation, for example:
> ./sysupgrade upgrade --cass_host NodeA-new
  1. 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. In this example, NodeA-new is the Cassandra host and must be specified using the --cass_host option when running upgrade on each node.
Note   If you are not using Apache Cassandra, run the upgrade command with the --no_cassandra option. For more information, see upgrade command options in the API Gateway Upgrade Guide.

If any issues are identified during upgrade, resolve them and rerun upgrade if required. You must resolve any errors before proceeding.

For more details on running upgrade for a multi-node domain see Multi-node upgrade example (upgrades from 7.3.x or 7.4.x) in the API Gateway Upgrade Guide.

Step 7 – Run apply on NodeA-new

To apply the upgrade, you must run the sysupgrade apply command on each of the new Axway Appliance Platform nodes (for example, NodeA-new, NodeB-new, and NodeC-new). However, because NodeA-new is the first Admin Node Manager, you must run apply on NodeA-new first.

Complete the following steps:

  1. Shut down all the old API Gateway Appliance processes on NodeA-old, NodeB-old, and NodeC-old.
  2. If you are using Apache Cassandra, start Apache Cassandra on the host you specified to the upgrade command (for example, NodeA-new). 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 Apache Cassandra in the API Gateway Installation Guide.
  5. Run the apply command on NodeA-new:
> cd /opt/Axway-7.5.3/apigateway/upgrade/bin
> ./sysupgrade apply --anm_host NodeA-new

The version 7.5.3Admin Node Manager and API Gateway Appliance are now running on NodeA-new.

For more details on running apply for a multi-node domain see Multi-node upgrade example (upgrades from 7.3.x or 7.4.x) in the API Gateway Upgrade Guide.

Step 8 – Run apply on remaining Axway Appliance Platform nodes

To complete the upgrade, run apply on the remaining nodes in turn (for example, NodeB-new then NodeC-new).

The following example shows how to run the apply command on each of the other nodes:

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

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

Step 9 – Verify the upgrade on all Axway Appliance Platform nodes

Verify the upgrade as detailed in Multi-node upgrade example (upgrades from 7.3.x or 7.4.x) in the API Gateway Upgrade Guide.

Related Links