Software AG Products 10.11 | Integrate Software AG Products Using Digital Event Services | webMethods API Gateway Documentation | Upgrading API Gateway | Upgrading | Upgrading Minor Versions in Zero Downtime | Upgrade Standalone Deployment
 
Upgrade Standalone Deployment
API Gateway follows the blue-green approach to upgrade a standalone deployment. There is no data migration as both the old and new versions would be pointing to the same API Data Store. The new API Gateway version is started and the old instance is blocked for core design time data updates. After that the new node's endpoint is added to the load balancer. At this time the transactions are served by both the old and new versions. Next, all the transactions to the old version is blocked and the logs and events data are migrated to the new version while it is serving the transactions.
The following image shows the workflow for a minor upgrade of standalone API Gateway instance.
1. Put old API Gateway instance in Quiesce mode for Design Time.
You must perform this operation on old instance of API Gateway. For a cluster, you must do this at each node as quiesce mode is enabled at the instance level.
API Gateway data in the API Data Store is migrated in two phases. In the first phase, only the design time data like APIs, applications, and policies are migrated. The runtime data like audit logs, transaction logs, performance metrics, and so on are migrated in the next phase (after the runtime transactions to the old instance are stopped). This is performed after the new instance is up and running with the new data and runtime traffic is allowed to it.
Before migrating design time data in the first phase, all the updates to them through UI and REST APIs must be blocked. This can be achieved by the quiesce mode capability available in API Gateway.
You can use the following API to enable Quiesce mode for design time in the old instance of API Gateway.
PUT /rest/apigateway/quiescemode

{
"enable": true,
"block": "designtime"
}
If the invocation is successful the API returns 200 OK message.
Now all the design time invocations to the old instance are blocked and API Gateway returns 503 message to the client. Only the following requests are allowed:
*All GET requests
*/rest/apigateway/quiescemode
*/rest/apigateway/search
*/rest/facade/apigateway/searchApis
When the quiesce mode for design time is complete, API Gateway sends out a notification with the result details through registered webhooks. You can also invoke the following REST API to check for the current status of the operation.
GET rest/apigateway/quiescemode
A Success status message implies that quiesce mode for design time is completed.
If the quiesce mode for design time API invocation fails with an error or the status returned with a failure, you must stop execution of the next steps and disable the quiesce mode for design time in all the nodes and bring them back to normal state. Contact Software AG support team in this case.
2. Start new API Gateway Instance.
You must install the new instance of API Gateway and perform the following prerequisite steps:
a. IS/File System Configurations and Custom Packages.
As zero downtime upgrade deals only with the migration of API Data Store data, the administrator must look after the migration of the non API Data Store configurations such as file system configurations, ports configurations (if port clustering is disabled), and custom ESB packages to the new API Gateway instance before running the migration of data.
The configurations are as follows:
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 you set the portClusteringEnabled extended setting to false, you must create server ports in each instance.
SAML SSO Configuration
You must ensure that the following file locations in SAML SSO configuration are accessible from the new instance. If not, you must manually copy those files to the new instance.
*IDP metadata location
*Gateway metadata location
*Keystore location
Custom ESB packages
You must ensure that all the custom packages are installed and ready in the new instance of API Gateway.
You can now start the new API Gateway instance by connecting it to the old API Data Store as external.
b. Add traffic to new API Gateway Instance
After the new API Gateway instance is restarted, the runtime traffic can be allowed to flow to it. Adding traffic to the new instance depends on the deployment model.
For example, for on-premise and Docker deployment, it would be an update to load balancer for adding the new endpoints. For Kubernetes deployment, it would be a label change in service resources.
c. Shutdown Old API Gateway Instance.
When the new instance is added to the load balancer, you can shutdown the old instance after all the active client sessions in that node are closed. This ensures that no metrics are sent to any configured destinations like API Portal, external Elasticsearch, and so on. The new instance is now receiving the runtime transactions. You can remove the old instance endpoint from the load balancer.
You can invoke the following API to shutdown API Gateway
POST /invoke/wm.server.admin/shutdown

{
"bounce": "no",
"option": "drain",
"timeout": 10
}
The timeout value depends on the number of active client sessions.
Note:
For 10.7 and above versions, you can use the API
/rest/apigateway/shutdown
to shutdown the API Gateway server.