API Gateway 10.11 | Upgrading and Migrating to API Gateway | Upgrading API Gateway | Introduction
 
Introduction
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.