Upgrading API Gateway with Zero Downtime

Edit online

The migration procedure outlined below seamlessly migrates webMethods API Gateway applications from version 10.15 to version 11.1 while ensuring zero downtime. This task specifically outlines the migration process for webMethods API Gateway instances deployed with API Data Store and alongside an external Elasticsearch.

This procedure accommodates various scenarios, including:

Migrating from single instance to another single instace
Migrating from clustered setup to other clustered setup

Prerequisites:

For migration of containerized webMethods API Gateway applications, download the latest source and target webMethods API Gateway container images.
Note: The target webMethods API Gateway version must be higher than the source webMethods API Gateway.
For migration of non-containerized webMethods API Gateway instances, install latest fixes in both source and target webMethods API Gateway versions.
Note: The target webMethods API Gateway version must be higher than the source webMethods API Gateway instance.
Create a source Elasticsearch repository to back up the source webMethods API Gateway by following these steps:
1. Configure the path.repo property in the Elasticsearch configuration file:
  In a non-containerized setup:
  
  Configure the path.repo property in the configuration file located at ../InternalDataStore/config/elasticsearch.yml, if you are using the embedded elasticsearch, else, the elasticsearch.yml should be in elasticsearch/config.
  
  In a containerized setup:
  
  Configure the path.repo property in the external Elasticsearch configuration file located at usr/share/elasticsearch/config.
  In Docker, add the following entry in the environment configuration section of your Docker configuration:
```
environment:
  - path.repo=path_to_your_backup_directory
```
  In Kubernetes, add the following entry in the environment configuration section of your Kubernetes configuration:
```
environment:
  - name: path.repo
    value: path_to_your_backup_directory
```
  This property specifies the directory where external Elasticsearch stores its backups. Ensure that external Elasticsearch has the required permissions to read from and write to the specified directory. You can modify this path to another directory of your choice.
  A sample configuration to configure the path.repo property in Docker is as follows:
```
environment:
  - path.repo=/usr/share/elasticsearch/backup
```
  In this example, the backups are stored at /usr/share/elasticsearch/backup.
  
  Note: Use a shared volume to map the path specified by path.repo in both the source and target Elasticsearch instances. This ensures the target instance can access the stored backups. Alternatively, copy the generated backups to your desired directory and configure path.repo to point to that directory.
2. Create a file system repository with type fs using the external Elasticsearch snapshot API in the source external Elasticsearch instance, using the following command:
```
PUT /_snapshot/{repositoryName}
{
"type": "fs",
"settings": {
"location": "path_to_your_backup_directory"
}
}
```
  Replace {repositoryName} with your chosen repository name and ensure the location field points to the desired directory where the backups are stored.
  
  Note: You may use this repository for future migrations. If you prefer to use the default repository names instead of specifying other names during migration, create repositories with the default names at this step. The default name for the core data repository is migration-core-repo, and the default name for the events and logs data repository is migration-eventsandlogs-repo.
3. Use the external Elasticsearch API to retrieve information about the registered repositories using the following command:
```
GET /_snapshot/{repositoryName}
```
  Replace {repositoryName} with your chosen repository name.
  
  This returns information about the {repositoryName} repository.
Create a target lasticsearch repository to restore the backup in the target webMethods API Gateway instance by following these steps:
1. Configure the path.repo property in the Elasticsearch configuration file:
  In a non-containerized setup:
  
  Configure the path.repo property in the configuration file located at ../InternalDataStore/config/elasticsearch.yml, if you are using the embedded elasticsearch, else, the elasticsearch.yml should be in elasticsearch/config.
  
  In a containerized setup:
  
  Configure the path.repo property in the external Elasticsearch configuration file located at usr/share/elasticsearch/config.
  In Docker, add the following entry in the environment configuration section of your Docker configuration:
```
environment:
  - path.repo=path_to_your_backup_directory
```
  In Kubernetes, add the following entry in the environment configuration section of your Kubernetes configuration:
```
environment:
  - name: path.repo
    value: path_to_your_backup_directory
```
  This property specifies the directory where external Elasticsearch stores its backups. Ensure that external Elasticsearch has the required permissions to read from and write to the specified directory. You can modify this path to another directory of your choice.
  A sample configuration to configure the path.repo property in Docker is as follows:
```
environment:
  - path.repo=/usr/share/elasticsearch/backup
```
  In this example, the backups are stored at /usr/share/elasticsearch/backup.
  
  Note: Use a shared volume to map the path specified by path.repo in both the source and target Elasticsearch instances. This ensures the target instance can access the stored backups. Alternatively, copy the generated backups to your desired directory and configure path.repo to point to that directory.
2. Create a file system repository with type fs using the external Elasticsearch snapshot API in the target external Elasticsearch instance and make it read-only for restoration, using the following command:
```
PUT /_snapshot/{repositoryName}
{
"type": "fs",
"settings": {
"location": "path_to_your_backup_directory"
"readonly": true
}
}
```
  Replace {repositoryName} with your chosen repository name and ensure the location field points to the desired directory where the backups are stored.
  
  Note: You may use this repository for future migrations. If you prefer to use the default repository names instead of specifying other names during migration, create repositories with the default names at this step. The default name for the core data repository is migration-core-repo, and the default name for the events and logs data repository is migration-eventsandlogs-repo.
3. Use the external Elasticsearch API to retrieve information about the registered repositories using the following command:
```
GET /_snapshot/{repositoryName}
```
  Replace {repositoryName} with your chosen repository name.
  
  This returns information about the {repositoryName} repository.

The following image illustrates the different stages of migration:

To migrate webMethods API Gateway instance

Set up the source webMethods API Gateway instance.
1. Start the source webMethods API Gateway instance. Ensure it starts up successfully.
2. Verify that the source webMethods API Gateway instance is running and in a healthy state before proceeding with the migration process.
  A sample command to check the health of the source webMethods API Gateway instance is as follows:
```
curl --location --request GET
'http://source-gateway:5555/rest/apigateway/health/engine' \
--header 'Authorization: Basic QWRtaW5pc3RyYXRvcjptYW5hZ2U='
```
```
curl --location --request GET
'http://source-gateway:5555/rest/apigateway/health/admin' \
--header 'Authorization: Basic QWRtaW5pc3RyYXRvcjptYW5hZ2U='
```
  If both commands return a green status and the response code is 200 Ok, the source webMethods API Gateway instance indicates a healthy state.
Set up the target webMethods API Gateway instance.
1. Start the target webMethods API Gateway instance. Ensure it starts up successfully.
2. Verify the target webMethods API Gateway instance is fully operational and in a healthy state before proceeding further with the migration process.
  A sample command to check the health of the target webMethods API Gateway instance is as follows:
```
curl --location --request GET
'http://target-gateway:5555/rest/apigateway/health/engine' \
--header 'Authorization: Basic QWRtaW5pc3RyYXRvcjptYW5hZ2U='
```
```
curl --location --request GET
'http://target-gateway:5555/rest/apigateway/health/admin' \
--header 'Authorization: Basic QWRtaW5pc3RyYXRvcjptYW5hZ2U='
```
  If both commands return a green status and the response code is 200 Ok, the target webMethods API Gateway instance indicates a healthy state.
Migrate core data.
Source webMethods API Gateway instance
1. Invoke the migrate/core/source REST API to initiate core data migration. A sample command to invoke the migrate/core/source REST API is as follows:
```
curl --location --request POST 'http://source-gateway:port_number/rest/apigateway/migrate/core/source' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic QWRtaW5pc3RyYXRvcjptYW5hZ2U=' \
--data '{
    "repoName": "",
    "snapshotName": ""
 }'
```
  In the migrate/core/source REST API, specifying the repoName and snapshotName fields is optional. If you omit these values, the default values are used. The default repoName is migration-core-repo. The default format for snapshotName is repoName_ddMMyyyy_hhmmss, where the timestamp indicates the time the snapshot was created. For example, if the snapshot is created at 12:49:54 on May 22, 2024, the snapshot name becomes migration-core-repo_22052024_124954.
  
  If you are not using the default repoName and snapshotName, you must explicitly provide the values for repoName and snapshotName. Make sure that the repoName matches the repository you have registered for Elasticsearch.
2. Monitor the migration status using the migrate/core/status REST API and wait until it is completed. A sample command to invoke the migrate/core/status REST API is as follows:
```
curl --location --request GET 'http://source-gateway:port_number/rest/apigateway/migrate/core/status' \
--header 'Authorization: Basic QWRtaW5pc3RyYXRvcjptYW5hZ2U='
```
3. If the migration is successful, proceed to the next step. If you have issues, troubleshoot using the following steps:
  1. Invoke the REST API migrate/rollback/source to disable quiesce mode. A sample command to invoke the migrate/rollback/source REST API is as follows:
```
curl --location --request POST 'http://source-gateway:port_number/rest/apigateway/migrate/rolllback/source' \
--header 'Authorization: Basic QWRtaW5pc3RyYXRvcjptYW5hZ2U='
```
  2. Save the server.log file located at /opt/softwareag/IntegrationServer/instances/source_tenant/logs/server.log from the source webMethods API Gateway instance for subsequent analysis. Create a report using the migrate/core/status REST API response for futher analysis. A sample command to invoke the migrate/core/status REST API is as follows:
```
curl --location --request GET 'http://source-gateway:port_number/rest/apigateway/migrate/core/status' \
--header 'Authorization: Basic QWRtaW5pc3RyYXRvcjptYW5hZ2U='
```
  3. Monitor the rollback status using the REST API migrate/rollback/status REST API. A sample command to monitor the rollback status is as follows:
```
curl --location --request GET 'http://source-gateway:port_number/rest/apigateway/migrate/rollback/status' \
--header 'Authorization: Basic QWRtaW5pc3RyYXRvcjptYW5hZ2U='
```
  4. For a containerized setup, if required, remove the target webMethods API Gateway container.
    A sample command to remove the target webMethods API Gateway container is as follows:
    docker rm container_id_or_name
Target webMethods API Gateway instance
1. Invoke the migrate/core/target REST API to initiate core data migration. A sample command to invoke the migrate/core/target REST API is as follows:
```
curl --location --request POST 'http://target-gateway:port_number/rest/apigateway/migrate/core/target' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic QWRtaW5pc3RyYXRvcjptYW5hZ2U=' \
--data '{
    "repoName": "",
    "snapshotName": "migration-core-repo_22052024_124954"
 }'
```
  In the migrate/core/target REST API, specifying the repoName field is optional. If you omit this value, the default value is used. The default repoName is migration-core-repo.
  Note: You must provide the snapshotName that you get from the migrate/core/status REST API response. If you do not specify the snapshotName, the migration fails.
  
  If you are not using the default repoName, you must explicitly provide the repoName. Make sure that the repoName matches the repository you have registered for external Elasticsearch.
2. Monitor the migration status using the migrate/core/status REST API and wait until it is completed. A sample command to invoke the migrate/core/status REST API is as follows:
```
curl --location --request GET 'http://target-gateway:5555/rest/apigateway/migrate/core/status' \
--header 'Authorization: Basic QWRtaW5pc3RyYXRvcjptYW5hZ2U='
```
3. If the migration is successful, proceed to the next step. If you have issues, troubleshoot using the following steps:
  1. Invoke the migrate/rollback/source REST API to disable quiesce mode. A sample command to invoke the migrate/rollback/source REST API is as follows:
```
curl --location --request POST 'http://source-gateway:port_number/rest/apigateway/migrate/rolllback/source' \
--header 'Authorization: Basic QWRtaW5pc3RyYXRvcjptYW5hZ2U='
```
  2. Save the server.log file located at /opt/softwareag/IntegrationServer/logs/server.log from the target webMethods API Gateway instance for subsequent analysis. Create a report using the migrate/core/status REST API response for futher analysis. A sample command to invoke the migrate/core/status REST API is as follows:
```
curl --location --request GET 'http://target-gateway:port_number/rest/apigateway/migrate/core/status' \
--header 'Authorization: Basic QWRtaW5pc3RyYXRvcjptYW5hZ2U='
```
  3. Monitor the rollback status using the migrate/rollback/status REST API. A sample command to monitor the rollback status is as follows:
```
curl --location --request GET 'http://source-gateway:port_number/rest/apigateway/migrate/rollback/status' \
--header 'Authorization: Basic QWRtaW5pc3RyYXRvcjptYW5hZ2U='
```
  4. For a containerized setup, if required, remove the target webMethods API Gateway container.
    A sample command to remove the target webMethods API Gateway container is as follows:
    docker rm container_id_or_name
Switch traffic.
1. After migrating the core data, initiate the traffic switch job externally.
2. If the traffic is switched successfully, proceed to the next step. If you have issues, troubleshoot using the following steps:
  - Invoke the migrate/rollback/source REST API to disable quiesce mode. A sample command to invoke the migrate/rollback/source REST API is as follows:
```
curl --location --request POST 'http://source-gateway:port_number/rest/apigateway/migrate/rolllback/source' \
--header 'Authorization: Basic QWRtaW5pc3RyYXRvcjptYW5hZ2U='
```
  - Monitor the rollback status using the migrate/rollback/status REST API. A sample command to monitor the rollback status is as follows:
```
curl --location --request GET 'http://source-gateway:port_number/rest/apigateway/migrate/rollback/status' \
--header 'Authorization: Basic QWRtaW5pc3RyYXRvcjptYW5hZ2U='
```
  - For a containerized setup, if required, remove the target webMethods API Gateway container.
    A sample command to remove the target webMethods API Gateway container is as follows:
    docker rm container_id_or_name
Migrate analytics data.
Source webMethods API Gateway instance
1. Invoke the migrate/eventsandlogs/source REST API to initiate the analytics data migration. A sample command to invoke the migrate/eventsandlogs/source REST API is as follows:
```
curl --location --request POST 'http://source-gateway:port_number/rest/apigateway/migrate/eventsandlogs/source' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic QWRtaW5pc3RyYXRvcjptYW5hZ2U=' \
--data '{
    "repoName": "",
    "snapshotName": ""
 }'
```
  In the migrate/eventsandlogs/source REST API, specifying the repoName and snapshotName fields is optional. If you omit these values, the default values are used. The default repoName is migration-eventsandlogs-repo. The default format for snapshotName is repoName_ddMMyyyy_hhmmss, where the timestamp indicates the time the snapshot was created. For example, if the snapshot is created at 12:49:54 on May 22, 2024, the snapshot name becomes migration-eventsandlogs-repo_22052024_124954.
  
  If you are not using the default repoName and snapshotName, you must explicitly provide the values for repoName and snapshotName. Make sure that the repoName matches the repository you have registered for Elasticsearch.
2. Monitor the migration status using the migrate/eventsandlogs/status REST API and wait until it is completed. A sample command to invoke the migrate/eventsandlogs/status REST API is as follows:
```
curl --location --request GET 'http://source-gateway:port_number/rest/apigateway/migrate/eventsandlogs/status' \
--header 'Authorization: Basic QWRtaW5pc3RyYXRvcjptYW5hZ2U='
```
3. If the migration is successful, proceed to the next step. If you have issues, troubleshoot using the following steps:
  1. You can retry migrating the analytics data.
  2. Save the server.log file located at /opt/softwareag/IntegrationServer/instances/source-tenant/logs/server.log from the source webMethods API Gateway instance for subsequent analysis. Create a report using the migrate/eventsandlogs/status REST API response for futher analysis. A sample command to invoke the migrate/eventsandlogs/status REST API is as follows:
```
curl --location --request GET 'http://source-gateway:port_number/rest/apigateway/migrate/eventsandlogs/status' \
--header 'Authorization: Basic QWRtaW5pc3RyYXRvcjptYW5hZ2U='
```
Target webMethods API Gateway instance
1. Invoke the migrate/eventsandlogs/target REST API to initiate the analytics data migration. A sample command to invoke the migrate/eventsandlogs/target REST API is as follows:
```
curl --location --request POST 'http://target-gateway:port_number/rest/apigateway/migrate/eventsandlogs/target' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic QWRtaW5pc3RyYXRvcjptYW5hZ2U=' \
--data '{
    "repoName": "",
    "snapshotName": "migration-eventsandlogs-repo_22052024_124954"
 }'
```
  In the migrate/eventsandlogs/target REST API, specifying the repoName field is optional. If you omit this value, the default value is used. The default repoName is migration-eventsandlogs-repo.
  Note: You must provide the snapshotName that you get from the migrate/eventsandlogs/status REST API response. If you do not specify the snapshotName, the migration fails.
  
  If you are not using the default repoName, you must explicitly provide the repoName. Make sure that the repoName matches the repository you have registered for external Elasticsearch.
2. Monitor the migration status using the migrate/eventsandlogs/status REST API and wait until it is completed. A sample command to invoke the migrate/eventsandlogs/status REST API is as follows:
```
curl --location --request GET 'http://target-gateway:port_number/rest/apigateway/migrate/eventsandlogs/status' \
--header 'Authorization: Basic QWRtaW5pc3RyYXRvcjptYW5hZ2U='
```
3. If the migration is successful, proceed to the next step. If you have issues, troubleshoot using the following steps:
  1. You can retry migrating the analytics data.
  2. Save the server.log file located at /opt/softwareag/IntegrationServer/logs/server.log from the target webMethods API Gateway instance for subsequent analysis. Create a report using the migrate/eventsandlogs/status REST API response for futher analysis. A sample command to invoke the migrate/eventsandlogs/status REST API is as follows:
```
curl --location --request GET 'http://target-gateway:port_number/rest/apigateway/migrate/eventsandlogs/status' \
--header 'Authorization: Basic QWRtaW5pc3RyYXRvcjptYW5hZ2U='
```
Stop or remove the source webMethods API Gateway instance.
After completing the data migration and successfully switching traffic to the new instance, stop or remove the old instance to avoid conflicts and resource wastage. Ensure all required data and services are migrated before decommissioning the source webMethods API Gateway instance.

A sample command, in a containerized setup, to stop and remove the source webMethods API Gateway container is as follows:

To stop the container
```
docker stop container_id_or_name
```
To remove the container
```
docker rm container_id_or_name
```
Perform final migration check.

Perform a final check to ensure the overall success of the migration process. Verify that all data and services are functioning correctly in the target webMethods API Gateway environment.