Upgrading standalone API Gateway using Direct mode

Pre-requisites:

Install the source and target API Gateway instances.

Note:
The version of target API Gateway must be higher than the source API Gateway instance. Supported source API Gateway versions are 10.1 and above.

Install latest fixes in both source and target versions.

If custom keystore files are used in the source API Gateway installation, copy the files to the same location in the target installation.

The API Gateway migration utility provides the support to:

Separately migrate Elasticsearch and API Gateway file configurations.

Migrate data from externally configured Elasticsearch.

Log all the migration data in a single file, that is migrationLog.txt.

Revert in case of failure in Elasticsearch data migration.

Note:
In the API Gateway versions 10.2 and above, the folder name EventDataStore is changed to InternalDataStore. Throughout this section, the source API Gateway installation directory is referred as <SOURCE>, target API Gateway installation directory is referred as <TARGET>, and the target Elasticsearch is referred as <TARGET_ELASTIC_SEARCH>.

To upgrade a standalone API Gateway instance using direct mode

1. Configure the reindex.remote.whitelist property in the target elasticsearch.yml file for re-indexing the data in the target Elasticsearch. This YAML file is located at <TARGET>\InternalDataStore\config. The reindex.remote.whitelist property copies the documents from the <SOURCE> to <TARGET> Elasticsearch instance.

Syntax for reindex.remote.whitelist property in the target elasticsearch.yml file is as follows:

reindex.remote.whitelist: <source_host>:<source_port>

Note:
The value of reindex.remote.whitelist property in the target elasticsearch.yml file must match the value of the pg.gateway.elasticsearch.hosts property present in the config.properties file located at <SOURCE>\IntegrationServer\instances\default\packages\WmAPIGateway\config\resource\elasticsearch.

2. Optional. Configure the source Elasticsearch host and port details in the config.properties file located at <SOURCE>\IntegrationServer\instances\default\packages\WmAPIGateway\config\resources\elasticsearch.

Syntax for Elasticsearch host and port details in the source config.properties file is as follows:

pg.gateway.elasticsearch.hosts=<source_host>:<source_port>

Note:
This step is applicable only if the source API Gateway version is 10.1. From versions 10.2 and above, the Elasticsearch host and port values are populated automatically.

3. Configure the basic authentication credentials to connect to the source Elasticsearch, if the source Elasticsearch is protected.

To configure the basic authentication credentials, add the following properties to the config.properties file located at <SOURCE>\IntegrationServer\instances\default\packages\WmAPIGateway\config\resources\elasticsearch:

pg.gateway.elasticsearch.http.username=<username>
pg.gateway.elasticsearch.http.password=<password>

4. Configure the certificates to connect to the source Elasticsearch.

If the source Elasticsearch is protected with HTTPS, add the source certificates (public key) into the target Elasticsearch JVM's truststore. For example, in case of API Data Store, add the public keys to the truststore cacerts file located at <TARGET>\jvm\jvm\jre\lib\security.

Note:
If, external Elasticsearch is used for the target API Gateway, then the certificates must be imported to its corresponding JVM.

Sample command to import the truststore of the source Elasticsearch into the target Elasticsearch JVM is as follows:

<TARGET>\jvm\jvm\bin\keytool -import -keystore <TARGET>\jvm\jvm\jre\lib\security\cacerts -file <truststore.jks> -alias <alias>

Property	Description
truststore.jks	Truststore used in <SOURCE> Elasticsearch. Provide the full path of the truststore. For 10.1, it is available at <SOURCE>\WmAPIGateway\config\resources\bean\gateway-es-store.xml and the property is <prop key="searchguard.ssl.http.truststore_filepath"\>sagconfig/root-ca.jks\</prop>. For 10.2 and above, it is available at <SOURCE>\WmAPIGateway\config\resources\elasticsearch\config.properties and the property is pg.gateway.elasticsearch.https.truststore.filepath. Example: sagconfig/root-ca.jks
alias	Alias used in <SOURCE> Elasticsearch. Example: wm.sag.com

5. Start both the source and the target Elasticsearch instances and make sure that API Gateway (Integration Server) instances are not started.

Note:
Avoid port conflict. If the source and target API Gateway instances are running in the same machine, then you might not be able to start both the source and target Elasticsearch instances in parallel with the default port configurations. In this case, the target Elasticsearch instance port can be changed temporarily for performing the migration. Both, HTTP and TCP ports must be changed. To change the target Elasticsearch instance ports:

a. Open the elasticsearch.yml file located at <TARGET>/InternalDataStore/config. Change the value of the HTTP port in the http.port property, TCP port in the transport.tcp.port property, and discovery.zen.ping.unicast.hosts properties.

b. Open the config.properties file located at <TARGET>/IntegrationServer/instances/default/packages/WmAPIGateway/config/resources/elasticsearch and find the pg.gateway.elasticsearch.hosts property. If the property is set to changeOnInstall, then do not make further changes to property. If a port is configured, then update it to a new value.

6. Go to <TARGET>\IntegrationServer\instances\default\packages\WmAPIGateway\bin\migrate and run the following migration utility command to migrate the Elasticsearch data and API Gateway configurations.

migrate.bat datastore -dstoreSrc <full path to source Elasticsearch config.properties>

Property	Description
dstoreSrc	If the source and target API Gateway instances are running on the same machine, provide the location where the <SOURCE> config.properties file is located. Sample command is as follows: migrate.bat datastore -dstoreSrc<SOURCE>\IntegrationServer\instances\default\packages\ WmAPIGateway\config\resources\elasticsearch\config.properties
dstoreSrc	If the source and target instances are running on different machines, then the source installation directory or at least the Elasticsearch config.properties file must be shared in the network. Otherwise, copy and paste the source config.properties file to the shared location. Sample command is as follows: migrate.bat datastore -dstoreSrc\chebackup01\installations\source\IntegrationServer\instances\default\ packages\WmAPIGateway\config\resources\elasticsearch\config.properties

7. Go to <TARGET>\IntegrationServer\instances\default\packages\WmAPIGateway\bin\migrate and run the following migration utility command to migrate the Integration Server configurations.

migrate.bat apigateway -srcDir <SOURCE> -instanceName <source instance name> -newInstanceName <target instance name>

Property	Description
srcDir	If the source API Gateway instance is installed on the same machine, provide the source API Gateway installation directory. Sample command is as follows: -srcDir C:\installations\source
srcDir	If the source API Gateway instance is installed on a different machine, then share the entire installation folder. Sample command is as follows: -srcDir \chebackup01\source
instanceName	Optional. Provide the <SOURCE> instance name that you want to migrate. If you do not provide any name, then a default name is assigned. Sample command is as follows: -instanceName test
newInstanceName	Optional. Provide the <TARGET> instance name that you want to migrate to. If you do not provide any name, then a default name is assigned. If you have created a new instance other than the default in Integration Server and you want to migrate to the new instance then provide its name. Sample command is as follows: -newInstanceName prod

File system configurations

The following configurations are persisted in the file system and some of those are covered using Integration Server migration. Verify the correctness of these configurations in the target environment after the migration procedures are completed. The migration utility does not migrate the configuration changes done in elasticsearch.yml, kibana.yml. You must migrate these configuration manually.

Note:
Most of the configurations can be configured using externalized configurations. For more information, see webMethods API Gateway Administration.

The configurations are listed below.

Configuration	File name	File location
Elasticsearch configuration	elasticsearch.yml	SAGInstallDir/InternalDataStore/config/
Elasticsearch client configuration	config.properties	SAGInstallDir/IntegrationServer/instances/instance_name/packages/WmAPIGateway/config/resources/elasticsearch/
Kibana configuration	kibana.yml	SAGInstallDir/profiles/instance_name/apigateway/dashboard/config/
Master password	mpw.dat	SAGInstallDir/profiles/instance_name/configuration/security/passman/
UI configurations	uiconfiguration.properties	SAGInstallDir/profiles/instance_name/apigateway/config/
SAML group mapping	saml_groups_mapping.xml	SAGInstallDir/IntegrationServer/instances/instance_name/packages/WmAPIGateway/config/resources/security/
WebApp settings	com.softwareag.catalina.connector.http.pid-apigateway.properties com.softwareag.catalina.connector.https.pid-apigateway.properties	SAGInstallDir/profiles/instance_name/configuration/com.softwareag.platform.config.propsloader/

Server Ports Configuration

If the portClusteringEnabled extended setting is set to false, the server ports must be created in each instance by the administrator.

SAML SSO Configuration

Ensure that the following files in SAML SSO configuration (SSO configuration done in API Gateway Admin UI) are accessible to the new instance. If not, manually copy these files to the new instance.

IDP metadata

Gateway metadata

Keystore

Custom ESB packages

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

8. Perform these steps after migrating the Integration Server configuration.

a. Shutdown the target Elasticsearch instance.

b. Start the target API Gateway server.

The API Gateway upgrade is complete.

You can find the logs at the target directory <TARGET>/install/logs/migrationLog.txt.

You can find the API Gateway migration reports at <TARGET>\install\logs\APIGW_Migration_Reports_<date_time>.