Upgrading standalone API Gateway using Backup 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 backup mode
1. Configure the path.repo property in the source elasticsearch.yml file to create a repository in Elasticsearch where the backup data is stored. This YAML file is located at <SOURCE>\InternalDataStore\config. Make sure that the path.repo is a shared network folder and is accessible for all the Elasticsearch nodes in the cluster. Start the source Elasticsearch instance.
Sample for path.repo property in the elasticsearch.yml file is as follows:
2. Back up the source API Gateway instance. Go to <SOURCE>\IntegrationServer\instances\default\packages\WmAPIGateway\cli\bin and run the following command.
Note:
Before you run the data backup command, create the backup destination directory.
apigw-upgrade-backup.bat -backupDestinationDirectory <path_to_data_store_backup_folder> -backupFileName <backup_file_name_without_spaces_for_the_zip>
Property | Description | Example |
backupDestinationDirectory | The location where the cumulative backup data is stored. | -backupDestinationDirectory C:\migration\backupFolder |
backupFileName | The name of the .zip file that is created when the backup command is executed. Make sure the backup file name is specified in lower case. | -backupFileName backupzipFile |
Sample command to backup data of the API Gateway instance is as follows:
apigw-upgrade-backup.bat -backupDestinationDirectory C:\migration\backupfolder -backupFileName backupzipfile
After the back up is successful, the backup directory contains the Elasticsearch data folder which is stored with the tenant name (default) and API Gateway configuration data as a ZIP file (backupzipfile.zip) as shown in the image below.
3. Stop the <SOURCE> Elasticsearch nodes after the source API Gateway instance data backup is completed.
4. Configure the path.repo property in the target elasticsearch.yml file to create a repository in Elasticsearch where the backup data is stored. The file is located at <TARGET_ELASTIC_SEARCH>\config. Start the target Elasticsearch instance.
5. Create a snapshot in the target Elasticsearch instance.
When the <TARGET_ELASTIC_SEARCH> Elasticsearch is up and running, invoke the following REST API to create a repository in the <TARGET> machine with the tenant name.
PUT /_snapshot/tenant_name
{
"type": "fs",
"settings": {
"location": tenant_name
}
}
For example, if you want to create a repository for default as tenant name, the sample command is as follows:
PUT /_snapshot/default
{
"type": "fs",
"settings": {
"location": "default"
}
}
After invoking the REST API, a folder with the tenant name, that is default' is created under the path.repo property folder.
6. Go to backupDestinationDirectory/<tenant_name> directory created in Step 2 and copy the contents from Elasticsearch data folder with the tenant name to the target repository under the path.repo folder.
Sample Elasticsearch data backup folder is shown in the image below:
Sample target repository folder is shown in the image below:
7. 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
8. 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 -srcFile <backup location>fileName.zip -instanceName <source instance name> -newInstanceName <target instance name>
Property | Description |
srcFile | Provide the backupFileName ZIP file location that was created as part of the backup process. This can also be a shared network file. Sample command is as follows: -srcFile C:\migration\backupfolder\backupzipfile.zip |
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 default |
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 default |
Sample migration utility command is as follows:
migrate.bat apigateway -srcFile C:\migration\backupfolder\backupzipfile.zip -instanceName default -newInstanceName default
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.
9. 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>.
