Quiesce Mode

Edit online

Quiescing webMethods API Gateway temporarily disables access to the server so you can perform the required tasks while the server is not connected to any external resources. In webMethods API Gateway the quiesce mode is used during the zero downtime upgrade wherein the access to the server is temporarily disabled, so you can perform the upgrade tasks.

webMethods API Gateway supports the following two types of quiesce mode:

Type 1: Blocks only design time requests.
In this mode webMethods API Gateway server blocks all design time requests such as all the CRUD operations for webMethods API Gateway assets like APIs, policies, applications, and so on, and returns an appropriate status code (503) to the client. The following requests are an exception and are still allowed by webMethods API Gateway:
- All GET requests
- /rest/apigateway/quiescemode
- /rest/apigateway/search
- /rest/facade/apigateway/searchApis
Type 2: Blocks all requests
In this mode webMethods API Gateway becomes unreachable for all the requests, design time, and runtime. Any requests that are already in progress are permitted to finish, but any new inbound requests to the server are blocked. This mode is an extension of the Integration Server quiesce mode, where webMethods API Gateway flushes the Quota, performance, and transaction license metrics data to the data store before the webMethods API Gateway package is disabled. While flushing the performance, license, and quota metrics data, webMethods API Gateway performs the following operations:
- Resets performance and license metrics intervals of the corresponding scheduler for all the APIs to be run immediately and flushes the data to be persisted into the database. For example:
  - webMethods API Gateway publishes performance metrics as per the Publish interval configured. That is, if the Publish interval is set as 60 seconds, then webMethods API Gateway publishes the performance metrics to the configured destination after 60 seconds. But, in quiesce mode webMethods API Gateway immediately publishes the performance metrics to the database.
  - webMethods API Gateway publishes transaction license metrics after 30 minutes, which is the default interval scheduled to publish the license metrics, to the data store. But in quiesce mode webMethods API Gateway immediately publishes the license metrics to the data store.
  In a cluster, only the controlling node performs this operation.
- Starts the subscription quota intervals and counters persisting scheduler immediately to store the data in the database. For example, webMethods API Gateway runs the subscription quota counters for an interval configured as per the pgmen.quotaSurvival.interval extended setting and publishes the data after the specified interval to the data store. But in quiesce mode webMethods API Gateway immediately publishes the quota metrics to the data store.
When all the performance metrics and other data are flushed completely, a notification mentioning that quiesce mode for all is enabled is sent through a webhook. The CRUD operations of webhook objects are supported in the Administration REST API of webMethods API Gateway. For more details, see webMethods API Gateway Administration API in the webMethods API Gateway Administration.

For details about quiesce mode in Integration Server, see IBM webMethods Integration Server Administrator’s Guide.

Enabling and Disabling Quiesce Mode

webMethods API Gateway provides a REST API to enable quiesce mode.

Enable or disable quiesce mode with the following REST call:

PUT /rest/apigateway/quiescemode

{
    "enable": true/false,
    "block": "designtime/all"
    "flush": [
        "license_metrics",
        "performance_metrics",
        "subscription_quota"
    ]
}

Set the block parameter as designtime to block only design time requests. The flush parameter is not applicable when you set the block parameter as designtime.

Set the block parameter as all to block all requests. The flush parameter is applicable when you set the block parameter as all. In the above example, when you set the block parameter as all, webMethods API Gateway blocks all the requests and flushes the license metrics, performance metrics, and subscription quota data. If you do not specify anything for the flush parameter, then all the data is flushed.

Set the enable parameter as true to enable quiesce mode.

Set the enable parameter as false to disable the quiesce mode. This is supported only when the block parameter is set as designtime. When the block parameter is set as all, webMethods API Gateway is quiesced and is unreachable. Hence, you cannot disable the webMethods API Gateway quiesce mode by invoking this API.

Use the Integration Server API POST /invoke/wm.server.quiesce/setActiveModeinvoke/wm.server.quiesce/setActiveMode, which is accessed through the quiesce port, to disable the Integration Server quiesce mode when the block parameter is set as all. This, in turn, disables the quiesce mode for all requests in webMethods API Gateway.

Note: For invoking the quiesce mode for all requests, you must specify the port through which the server enters and exits quiesce mode. For details about specifying the quiesce port, see IBM webMethods Integration Server Administrator’s Guide.

Retrieve the quiesce mode settings as well as the current status with the following REST call.

GET /rest/apigateway/quiescemode

{
    "enable": true/false,
    "block": "designtime/all"
    "flush": [
        "license_metrics",
        "performance_metrics",
        "subscription_quota"
    ],
    "status": "success",
    "failureReason": null
}

Migrate the design time data

When the old webMethods API Gateway instance is put into quiesce mode for design time, it is safe to migrate the design time data to the new webMethods API Gateway instance's external Elasticsearch.

You can run the following request in the new webMethods API Gateway instance to migrate the design time data. For a cluster, you must do this only on one of the instances. If the external Elasticsearch is protected with basic authentication, send the username and password in the request payload.

The source tenant name is assumed as default. But, if the source webMethods API Gateway has multiple tenants, this property can be used to specify the tenant name from which the data has to be migrated to the target tenant.

POST /rest/apigateway/migration

{
    "action": "reindex",
    "indicesType": "core",
    "sourceElasticsearch": {
        "url": "http://localhost:9200",
        "username": "username",
        "password": "password"
    },
    "properties": {
        "apigateway.migration.srcTenantName": "default",
        "apigateway.migration.batchSize": 100,
        "apigateway.migration.logLevel": "info",
        "apigateway.migration.reindex.status.check.sleep.interval": 5000,
        "apigateway.migration.batchSize.gateway_{0}_apis": 50,
        "apigateway.migration.batchSize.gateway_{0}_log": 100,
        "apigateway.migration.batchSize.gateway_{0}_audit_auditlogs": 50,
        "apigateway.migration.batchSize.gateway_{0}_analytics_transactionalevents": 50
    }
}

Note: If the Elasticsearch is secured, add the following parameters to the POST call:


"sourceElasticsearch": 
{
  "url": "https://localhost:9250",
  "username": "Administrator",
  "password": "manage",
  "keystoreFilePath":"<Elastic_Dir>/sagconfig/node-0-keystore.jks",
  "keystorePassword":"a362fbcce236eb098973",
  "truststoreFilePath":"<Elastic_Dir>/sagconfig/truststore.jks",
  "truststorePassword":"2c0820e69e7dd5356576",
  "keystoreAlias":"cn=node-0"
},

Since this is a long running operation, the request initiates the migration and returns 201 Accepted message, if the invocation is successful.

When the reindex operation is completed, webMethods API Gateway sends out a notification with the result details through registered webhooks. You can run the following request to check the status of the operation. .

GET
        /rest/apigateway/migration/status?action=reindex

A success status message implies that the re-indexing is completed.

If the re-index request invocation for design time data fails with an error or the status returned with a failure, stop proceeding with the next steps. Disable the quiesce mode for design time in all the nodes and bring them back to normal state. Clean the data and retry. If the error persists, contact IBM support team for help with all the relevant logs for further analysis.