Upgrade Standalone Deployment

About this task

webMethods API Gateway follows the blue-green approach to upgrade a standalone deployment. In such deployment scenario, old instance are allowed to run and serve the transactions while the new webMethods API Gateway version is being prepared. There is no data migration as both the old and new versions would be pointing to the same Elasticsearch or API Data Store. The new webMethods 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 a standalone webMethods API Gateway instance.

To upgrade webMethods API Gateway minor versions in zero downtime

Procedure

Put the old webMethods API Gateway instance in quiesce mode for design time.
You must perform this operation on the old webMethods API Gateway instance.

webMethods API Gateway data in the Elasticsearch or 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, that is, after the runtime transactions to the old instances 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 using the quiesce mode capability available in webMethods API Gateway.
Run the following request to enable quiesce mode for design time in the old webMethods API Gateway instance.
```
PUT /rest/apigateway/quiescemode

{
    "enable": true,
    "block": "designtime"
}
```
If the invocation is successful, webMethods API Gateway returns 200 OK message.
Now, all the design time invocations to the old instance are blocked and webMethods 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, webMethods API Gateway sends out a notification with the result details through registered webhooks. You can also run the following request to check the status of the operation.
```
GET rest/apigateway/quiescemode
```
A success status message implies that quiesce mode for design time is complete.

If the quiesce mode for design time request invocation fails with an error or the status returned with a failure, you must stop the execution of the next steps. Disable the quiesce mode for design time in all the nodes and bring them back to normal state. If the error persists, contact Software AG support team for help with all the relevant logs for further analysis.
Start the new webMethods API Gateway instance.
You must install the new instance of webMethods API Gateway and perform the following steps:
1. As zero downtime upgrade deals only with the migration of Elasticsearch or API Data Store data, the platform configurations and must be migrated to the new webMethods API Gateway instance either manually or using the externalized configurations.
  
  For more information on the platform configurations that must be migrated to the target webMethods API Gateway instance, see Migrating the platform configurations.
  
  You can now start the new webMethods API Gateway instance by connecting it to the old Elasticsearch or API Data Store as an external.
Add traffic to the new webMethods API Gateway instance.

After the new webMethods 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.
Shutdown the old webMethods 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 run the following request to shutdown the old webMethods API Gateway instance.
```
POST /rest/apigateway/shutdown

{
    "bounce": "true/false",
    "option": "force/drain",
    "timeout": 10,
    "quiesce": "true/false"
}
```
The timeout value depends on the number of active client sessions.
The webMethods API Gateway upgrade is complete. You can find the logs at the target directory <TARGET>/profiles/IS_profile name/logs/wrapper.log.