Introduction

Edit online

This guide explains how to upgrade API Gateway from versions 10.1 and above to a latest version. Upgrading API Gateway involves migrating the configurations and data from one version to another.

API Gateway manages different types of data that are migrated during an upgrade. This includes the data that are stored in Elasticsearch and in the file system.

The following table lists the different types of data and the migration procedure that API Gateway supports:

Data Type How is it stored? Where is it stored? Migration information
API Gateway assets Documents API Data Store or Elasticsearch For more information on the procedure to migrate these data, see Migrating the API Gateway assets and the analytics data.
API Gateway analytics Documents API Data Store or Elasticsearch For more information on the procedure to migrate these data, see Migrating the API Gateway assets and the analytics data.
Platform configurations Files On server nodes For more information on the procedure to migrate these data, see Migrating the platform configurations.

Terminologies used

Terminology Description
Source The source API Gateway installation directory.
Target The target API Gateway installation directory.
Quiesce Quiescing API Gateway temporarily disables access to the server so you can perform the required tasks while the server is not connected to any external resources. In API Gateway, quiesce mode is used during the zero downtime upgrade wherein the access to the server is temporarily disabled, so you can perform the upgrade tasks. For more details, see Quiesce Mode.
Blue-Green API Gateway follows Blue-Green deployment approach to upgrade to newer version in zero downtime.

Blue-green deployment is a technique that reduces the downtime and risk by running two identical production environments called blue and green. In such a deployment scenario, the old instance of API Gateway is allowed to run and serve the transactions while the new instance of API Gateway is being prepared for data migration.

Migrating the API Gateway assets and the analytics data

When you upgrade API Gateway to a latest version, you have to migrate the API Gateway assets and the analytics data, that is, the Elasticsearch or API Data Store data. If the source Elasticsearch or API Data Store instance is accessible by the target, then you can use the migrate.bat datastore command to migrate the API Gateway assets and the analytics data.

Note: If you do not have the connectivity between the source and the target Elasticsearch or API Data Store instances, contact the Software AG support team to set up the data migration.

When you use the migrate.bat datastore command, it migrates both the core and analytics data. When the analytics data is of high volume, alternatively, you can use the migrate.bat datastore command to migrate only the core data, and use the backup and restore command to migrate the analytics data.

When you migrate using migrate.bat datastore command, it also migrates ports, keystores, aliases, and so on, which is also stored in the API Data Store, and these values override the existing port configurations and keystores in target server. Hence, ensure that the unnecessary data such as migrated ports, keystores, and aliases are cleaned up post migration if they are not used by the target system.

For more information on the procedure to upgrade API Gateway and the migration utility command, see Upgrading standalone API Gateway and Upgrading API Gateway cluster.

Migrating the platform configurations

The platform configurations are mostly one time configurations, that is, these configurations do not change often and these configurations are stored in the version control system or similar repositories. These configurations must be migrated from the source to the target API Gateway instance. You can use these stored configurations to set up the target API Gateway instance and restore the configurations.

There are three ways to migrate the platform configurations from the source to the target API Gateway instance:

  1. Migrating the platform configurations manually, that is, copy the configuration files manually from the source repository to the target repository, to restore the target API Gateway instance, if you have stored these configurations in the repositories.
  2. Configuring using the externalized configurations. If you have externalized the configurations of the source API Gateway instance, you can use the same externalized configuration file to restore the target platform configurations. For more information, see webMethods API Gateway Administration.
    Note: Externalized configurations does not support externalizing all the API Gateway configurations. In future releases, API Gateway will support externalizing all the configurations.
  3. Using the migrate.bat apigateway command.

The following table shows the API Gateway configurations that are stored in the file system:

Configuration File name File location Is this supported by externalization? Is this data migrated by the migrate.bat utility command?
Elasticsearch configuration elasticsearch.yml SAGInstallDir/InternalDataStore/config/ No No
Elasticsearch client configuration config.properties SAGInstallDir/IntegrationServer/instances/​instance_name/packages/WmAPIGateway/​config/resources/elasticsearch/ Yes No
Kibana configuration kibana.yml SAGInstallDir/profiles/instance_name/​apigateway/dashboard/config/ Yes No
Master password mpw.dat SAGInstallDir/profiles/instance_name/​configuration/security/passman/ Yes Yes
UI configurations uiconfiguration.​properties SAGInstallDir/profiles/instance_name/​apigateway/config/ No Yes
WebApp settings

com.softwareag.catalina.​connector.http.​pid-apigateway.properties

com.softwareag.catalina.​connector.https.​pid-apigateway.properties

You have to manually migrate the certificates used for the WebApp ports.

SAGInstallDir/profiles/instance_name/​configuration/​com.softwareag.platform.config.​propsloader/ Yes Yes
Custom wrapper settings custom_wrapper.conf SAGInstallDir/profiles/instance_name/configuration/ No Yes
Server Ports Configuration If the portClusteringEnabled extended setting is set to false, you must create the server ports in each instance. No No
Custom ESB packages File name specified by users.

Make sure that all the custom packages are installed and ready in the new instances.

Location used by users to save the file.

Generally, the customized packages are saved in the following location: SAGInstallDir\IntegrationServer\tenant\packages\

No Yes

For more information on the procedure to upgrade API Gateway and the migration utility command, see Upgrading standalone API Gateway and Upgrading API Gateway cluster.