Before you upgrade from 7.3.x or 7.4.x

This topic describes the steps that you must perform before you upgrade from API Gateway 7.3.x or 7.4.x. It includes checks for your old API Gateway installation and for your new API Gateway 7.5.3 installation. It also includes checks you should perform if you are upgrading without Apache Cassandra. It includes the following sections:

Checklist for the old API Gateway installation

You must perform the following in your old API Gateway installation:

Back up the old API Gateway installation

Back up the old API Gateway installation on each node. At a minimum:

  • Back up the apigateway directory.
  • Back up any databases used by API Gateway, including external databases used for OAuth or KPS, and your metrics database if you are using API Gateway Analytics.

For more details on what you should back up, see API Gateway backup and disaster recovery in the API Gateway Administrator Guide.

Check that old API Gateway groups are consistent

Before you upgrade, ensure that all API Gateway groups in the old installation are consistent, meaning that all API Gateways in a group have the same configuration deployed. Upgrade is not supported for inconsistent groups.

You can use Policy Studio or API Gateway Manager to deploy configuration to API Gateway groups. For more details, see the API Gateway Administrator Guide.

Do not update the old API Gateway installation

Do not make any changes to the old API Gateway installation after the upgrade process has begun. For example, if you have run any sysupgrade commands, do not perform any of the following on the old installation:

  • Do not make any topology changes (for example, add new API Gateway instances)
  • Do not deploy any configuration
  • Do not update the API Gateway admin user store
  • Do not update API Manager configuration (for example, add new APIs, organizations, or applications)

See also What happens if you change the old API Gateway installation after running export?

Check that embedded Apache Cassandra is configured correctly in the old installation

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. In earlier versions Cassandra was embedded in the API Gateway process.

For API Gateway versions with embedded Cassandra, you must ensure that embedded Cassandra has been configured correctly in the old API Gateway installation. In particular, there are specific requirements for API Manager high availability (HA). For more details, see Configure high availability in the API Manager 7.4.1 API Management Guide.

Check that ext/lib customizations in the old installation are compatible

If you have customizations (for example, third-party JAR files) in the ext/lib directory of your old API Gateway installation, the sysupgrade command copies any third-party JARs to the new installation. However, you must verify that all third-party JARs are compatible with API Gateway 7.5.3.

Before you upgrade, you should confirm that any third-party JARs are not already present in the new installation under directory apigateway/system/lib. You should also test any custom JARs to ensure that they work correctly in API Gateway 7.5.3.

For more details, see the API Gateway Developer Guide.

Update custom filters in API Gateway version 7.3.1 or earlier

If you are upgrading from API Gateway version 7.2.2 or 7.3.1, and you have developed any custom API Gateway filters in your old installation, you must update your custom filter classes and recompile before upgrading. We recommend that you update your custom filters and recompile them in a 7.5.3 development environment before commencing an upgrade.

The upgrade copies any custom filter classes from ext/lib in the old installation to the same location in the new installation. After the upgrade, you must manually remove any incompatible JARs from ext/lib in the new installation, and manually copy the recompiled classes to ext/lib so that API Gateway can use them. You must also restart any API Gateways that use the custom filters.

For more details on the changes to classes, see the API Gateway Developer Guide.

Upgrade API Gateway Analytics version 7.4.0 or later

If you are using API Gateway Analytics version 7.4.0 or later, you can upgrade API Gateway Analytics before you run the sysupgrade command. For more information, see Upgrade API Gateway Analytics.

Update scripting language filters

If you are upgrading from 7.4.0 or earlier, and you are using a Scripting Language filter in your old installation with the Language field set to JavaScript (Rhino engine JRE7 and earlier), you must change the Language of the filter to JavaScript and ensure that the JavaScript syntax in the script conforms with Nashorn engine syntax.

If you do not make these changes, the script continues to work in your new installation, but with a severe drop in performance.

Updating your script to conform with Nashorn engine syntax typically involves replacing the importPackage statement, as the following example shows.

Original script:

importPackage(Packages.com.vordel.common.base64);

function invoke(msg)         
{        
    var base64EncodedData = msg.get("data.base64");
    var dataDecoded = Decoder.decodeToString(base64EncodedData);
    msg.put("data.decoded", dataDecoded );
    return true;        
}

Updated script (complies with Nashorn engine syntax):

var base64Import = new JavaImporter(com.vordel.common.base64);
 with(base64Import) {
     function invoke(msg) {
         var base64EncodedData = msg.get("data.base64");
         var dataDecoded = Decoder.decodeToString(base64EncodedData);
         msg.put("data.decoded", dataDecoded);
         return true;
     }
 };

For more information about migrating from Rhino to Nashorn, see the Rhino Migration Guide.

Identify components and configuration requiring manual upgrade steps

Not all components and configuration from earlier API Gateway versions can be upgraded automatically with the sysupgrade command. However, you can upgrade these items manually.

Check your old installation and identify if you are using any of the following:

  • Redaction files – For more information on migrating redaction files, contact Axway Support.
  • Customizations to OAuth sample .md files – For more information on upgrading these files, contact Axway Support.
  • API firewalling – For more information on upgrading API firewalling, contact Axway Support.
  • REST APIs developed using the Policy Studio REST API wizard – This wizard was available in earlier API Gateway versions (for example, 7.2.2). For more information on migrating these REST APIs, contact Axway Support.
  • Salesforce connector – For more information, see Update Salesforce connector license.
  • QuickStart tutorial – For more information on migrating the QuickStart tutorial, see Migrate the QuickStart tutorial.
  • API Gateway services – If you are running API Gateway processes as services on UNIX/Linux or Windows, you must upgrade these manually. See Upgrade services.

Checklist for the new API Gateway 7.5.3 installation

Perform the following in your new API Gateway 7.5.3 installation:

Install the latest service pack

Install the latest available service pack to your new installation. Service packs are available from Axway Support at https://support.axway.com.

Do not start any Node Managers or API Gateways in the new installation

Do not create or start any Node Managers, groups, or API Gateways in the new installation. These are started automatically by the sysupgrade process.

Configure an Apache Cassandra database cluster in the new installation

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.

Before you run the sysupgrade apply step, you must set up an appropriate Apache Cassandra database cluster:

  • For upgrade of a single-node or multi-node domain, only one Cassandra server is required in this cluster, and this server receives the upgraded data.
  • For upgrade of a multi-node domain, you must not enable authentication on this Cassandra server.
  • After the upgrade, you can add more nodes to this cluster to provide high availability (HA), and configure TLS security.

For more information on configuring an Apache Cassandra database cluster, see Install Apache Cassandra in the API Gateway Installation Guide.

Move third-party JDBC JARs to the new installation

If your old API Gateway installation uses external third-party databases for OAuth and KPS, you must copy the JDBC JAR files to the following location in your new 7.5.3 installation:

/apigateway/upgrade/lib

For example, if your new installation is at /opt/Axway/7.5.3, copy the JDBC drivers to /opt/Axway/7.5.3/apigateway/upgrade/lib.

This enables the sysupgrade apply step to upgrade the databases.

Checklist for upgrades without Apache Cassandra

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

To upgrade without Apache Cassandra, perform the following in your old API Gateway installation:

Delete or update Apache Cassandra-backed KPS collections in the old installation

Earlier versions of API Gateway might contain Apache Cassandra-backed KPS collections by default. If you do not wish to install or use Apache Cassandra in your new installation, you must delete these KPS collections, or update them to use an alternative data source, before you upgrade.

Follow these steps:

  1. Open the policystudio.ini file in your old installation (for example, /opt/Axway-7.4.1/policystudio/policystudio.ini) and add the following line:
-Dshow.internal.kps.collection=true
  1. Start Policy Studio and open the project containing the configuration for your old installation.
  2. In the Policy Studio tree, navigate to Environment Configuration > Key Property Stores.
  3. To delete a KPS collection (for example, API Server), right-click the KPS collection and select Delete.
  4. To update a KPS collection to use an alternative data source (for example, a database), click the Browse button next to the Default Data Source field and select a new data source.
  5. Save and deploy the configuration.

You can now proceed with the upgrade. You must run the sysupgrade upgrade step with the --no_cassandra option. For more details on this option, see upgrade command options.

Related Links