Single-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 version 7.5.3 in a single-node domain. The sysupgrade script includes validation features to guide you through the steps. This topic describes each step in detail.

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

Sample API Gateway topology

In this example, API Gateway 7.4.1 has a single-node topology that includes one Admin Node Manager and one API Gateway instance. There is a single API Gateway group.

The example topology is shown in the following diagram:

Single-node topology

Step 1 – Check the old installation

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

In addition, if you do not wish to install or use Apache Cassandra in your new installation, perform the checks detailed in Checklist for upgrades without Apache Cassandra.

Step 2 – Install API Gateway 7.5.3

Complete the following steps to install API Gateway 7.5.3:

  1. Select the Custom option in the installer, and select the following components:
    • Admin Node Manager.
    • API Gateway Server.
    • Policy Studio – Select this only if you want to run Policy Studio on the local machine.
    • API Manager – Select this only if you are upgrading API Manager.
    • Cassandra – Select this only if you want to install an Apache Cassandra database on the local machine alongside API Gateway. Apache Cassandra is required if you are upgrading API Manager, or if you are using Apache Cassandra for custom KPS data, for OAuth client application data, or for API keys in your old API Gateway installation. If you install Cassandra, you will also need to configure a Cassandra cluster. For more details, see Configure an Apache Cassandra database cluster in the new installation.
  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, enter a new directory (for example, /opt/Axway-7.5.3). A warning message displays if you try to install 7.5.3 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

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

Step 4 – Run export and upgrade commands

Perform the following steps:

  1. Ensure that the old API Gateway processes are running. This includes, for example, all Admin Node Managers, Node Managers, and API Gateway instances. These processes must be running in the old installation to export the API Gateway configuration data.
  2. Change to the upgrade/bin directory in the new API Gateway 7.5.3 installation, for example:
> cd /opt/Axway-7.5.3/apigateway/upgrade/bin
  1. Export the data from the old installation, specifying the full path of the old installation. For example, if your old installation is version 7.4.1:
> ./sysupgrade export --old_install_dir /opt/Axway-7.4.1/apigateway/
  1. If any issues are identified during export, resolve them and rerun export if required.
  2. Validate and upgrade the exported data.
  3. If you are using Apache Cassandra, 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 192.0.2.0
  1. For more information, see Update your Apache Cassandra database connection details.
  2. If you are not using Apache Cassandra, run the upgrade command as follows:
> ./sysupgrade upgrade --no_cassandra
  1. For more information on the --no_cassandra option, 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.

Step 5 – Run apply command

Perform the following steps:

  1. Stop the API Gateway processes in the old installation.
  2. If you are using Apache Cassandra in the new installation, start Apache Cassandra. Cassandra must be started before running apply. For more information on starting Cassandra, see Install Apache Cassandra in the API Gateway Installation Guide.
  3. Apply the upgrade to the new installation:
> ./sysupgrade apply
  1. This upgrades the external OAuth and KPS databases (if necessary), creates a new system that matches the old topology, and imports the upgraded data.

When all steps have completed successfully, the new API Gateway version 7.5.3 processes should be running.

Note   On Windows, you are prompted to start the Node Manager, and the upgrade process starts the API Gateway instance. On UNIX/Linux the Node Manager and API Gateway instances are started by the upgrade process.

Step 6 – Verify the upgrade

To verify that the upgrade has been successful, perform the following steps:

  1. Connect to API Gateway Manager (for example, on https://HOST:8090/), and view the API Gateway group topology, administrator users, and Key Property Stores. For more details, see the API Gateway Administrator Guide.
  2. Start Policy Studio, and create a new project based on the running API Gateway. You can view the upgraded configuration (for example, policies, settings, and so on). For more details, see the API Gateway Policy Developer Guide.
  3. If you were using OAuth client applications in your old installation, start the Client Application Registry web interface, and view the client applications. For more details, see the API Gateway OAuth User Guide.

Update your Apache Cassandra database connection details

Note    
  • This section applies to Apache Cassandra users who are upgrading from API Gateway versions earlier than 7.5.1 only. For example:
    • If you are using API Manager in your old installation, Apache Cassandra is required and this section applies.
    • If you are using Apache Cassandra for custom KPS data, for OAuth client application data, or for API keys in your old installation, this section applies.
  • If you are not using Apache Cassandra, or if you are upgrading from API Gateway 7.5.1 or later you can skip this section.

In API Gateway 7.5.1 and later versions, Cassandra runs externally to the API Gateway process. By default, data for all groups resides in a single Cassandra cluster.

In earlier versions of API Gateway, Cassandra was embedded in the API Gateway process. When you upgrade from an installation with an embedded Cassandra database to an installation with an external Cassandra database, you must run the sysupgrade upgrade command with the Cassandra options, to update the Cassandra connection details in the API Gateway configuration. When running upgrade, you must specify the new external Cassandra connection details including the Cassandra node IP address and port. You can also specify an optional Cassandra user name and password. For more details, see upgrade command options.

The sysupgrade apply command then imports the embedded KPS data from your old installation to the new external Cassandra database cluster. API Gateway group data is placed into a keyspace: x${DOMAIN_ID}_${GROUP_ID}, where DOMAIN_ID is the topology ID of the system being upgraded, and GROUP_ID is the API Gateway group ID. The replication factor is set to 1, and read/write consistency levels are set to ONE/ONE. This setup enables import into a 1-node or N-node Cassandra cluster, and places data into a known starting point to apply HA and security after upgrade. This supports 1-node (consistent), 2-node, or N-node eventual consistency.

Note   If you have not already set up a Cassandra cluster, you must set one up before running the apply step. For more details, see Configure an Apache Cassandra database cluster in the new installation. If you rerun export after running apply, you must first shut down the new Cassandra cluster if it is running on the same hosts as the old API Gateway installation.

Related Links