Obtain health check data of Management servers by using REST API calls

Call a health check API from your external load balancer to dynamically determine whether a specific Management server is up (ready to receive requests), or down (there is an issue with the server and it cannot receive requests). In addition there is an accompanying health check API that can be called and, if authenticated, it returns more detailed information about the health status of the Management server.

Tests run during the health checks

You can run either a simple health check or a detailed health check, but both checks run the same tests. The detailed health check returns more information for the same tests than the simple health check. The tests report the following information:
  1. Whether the server is considered to be in an active state.
  2. Whether the server is able to read documents from the configuration database.
  3. Whether the server is able to write documents to the configuration database.
  4. Whether the server is able to use the CouchDB database.
  5. Whether the server is a member of a management service with the provided display name.
  6. Whether the server is in the list of servers.
  7. Whether the cloud is dissociated.

Simple health check API

The simple health check API runs a series of tests on the Management server to determine whether the server is working correctly enough to be part of a load balancer configuration. See Tests run during the health checks for a list of the tests that are included in the simple health check.

To run a simple health check, configure your load balancer to make the following call:
https://address_of_mgmt_server/v1/servers/self/lb-health-check
Where address_of_mgmt_server is the IP address or hostname of a specific Management server. This cannot be the load balancing address.
You can optionally add the display name of the management service to the call. Adding the name ensures that the load balancer includes only management servers for a specific IBM® API Connect cloud, and is not misconfigured to reference one or more management servers in a different cloud. You can customize the default display name Management of the management service of your clouds to be more specific. For example, you might use something like Production, Development, or Test as a display name. If you want to use the additional name in the call, issue the following call:
https://address_of_mgmt_server/v1/servers/self/lb-health-check?clusterName=name_of_mgmt_service
Where the following substitutions are made according to your environment:
  • address_of_mgmt_server is the IP address or hostname of a specific Management server. This cannot be the load balancing address.
  • name_of_mgmt_service is the display name of the management service in the Cloud Manager. See Configuring the Management service for more information.
The following response messages are returned:
  • On success (if all tests pass), the API responds with an HTTP status code of 200, and the response body contains {"status":"success"}.
  • On failure (if any one test fails), the API responds with an HTTP status code of 409, and the response body contains {"status":"failure"}.
  • Any other 3XX, 4XX, or 5XX status code is a health check failure.

This API is available both through HTTP and HTTPS protocols, and does not require authentication.

Detailed health check API

The detailed health check API runs a series of tests on the Management server to determine whether the server is working correctly enough to be part of a load balancer configuration, and returns the results of those tests. See Tests run during the health checks for a list of the tests that are included in the detailed health check.

To run a detailed health check, configure your load balancer to make the following call:
https://address_of_mgmt_server/v1/servers/self/lb-health-check/details
Where address_of_mgmt_server is the IP address or hostname of a specific Management server. This cannot be the load balancing address.
You can optionally add the display name of the management service to the call. Adding the name ensures that the load balancer includes only management servers for a specific IBM API Connect cloud, and is not misconfigured to reference one or more management servers in a different cloud. You can customize the default display name Management of the management service of your clouds to be more specific. For example, you might use something like Production, Development, or Test as a display name. If you want to use the additional name in the call, issue the following call:
https://address_of_mgmt_server/v1/servers/self/lb-health-check/details?clusterName=name_of_mgmt_service
Where the following substitutions are made according to your environment:
  • address_of_mgmt_server is the IP address or hostname of a specific Management server. This cannot be the load balancing address.
  • name_of_mgmt_service is the display name of the management service in the Cloud Manager. See Configuring the Management service for more information.
Important: The detailed health check API call must be authenticated (you must pass Cloud Manager admin credentials to the Management server). The credentials that are required for the detailed health check must be prefixed with 'cmc/account_name'. An authentication error occurs if you do not apply the 'cmc/' prefix.
The following response messages are returned:
  • On success (if all tests pass), the API responds with an HTTP status code of 200, and the response body contains details of each individual test.
  • On failure (if any one test fails), the API responds with an HTTP status code of 409, and the response body contains details of each individual test, including information about the test or tests that have failed.
  • Any other 3XX, 4XX, or 5XX status code is a health check failure.

Query parameters

The following table shows the query parameters that can be used with both health check APIs.
Table 1. Query parameters for the health check APIs
Name of parameter Type Default Description
onSuccess Integer 200 The HTTP status code to respond with on success.
onFailure Integer 409 The HTTP status code to respond with on failure.
testIsActive Boolean true Controls whether the test to check if the server is considered to be in an active state, is run.
testIsReadable Boolean true Controls whether the test to check if the server is able to read documents from database, is run.
testIsWritable Boolean false Controls whether the test to check if the server is able to write documents to the database, is run.
testIsCouchUp Boolean true Controls whether the test to check if the server is able to use the CouchDB database, is run.
testIsInCluster Boolean true Controls whether the test to check if the server is a member of a management service with the provided display name, is run.
Note: If set to true, the clusterName parameter must also be set.
clusterName String   Display name of the management service to use when running the test to check whether the server is a member of a specific management service.
Note: If the testIsInCluster parameter is set to true, the clusterName must be set.
testIsInServers Boolean true Controls whether the test to check if the server is in the list of servers, is run.
[V5.0.8 or later]failIfCloudIsDissociated (version 5.0.8.3, and later) Boolean false Specifies whether to fail the test if there are Management servers that are identified as dissociated. See Dissociation and your cloud for more information.
testIsDissociated (deprecated) Boolean true Controls whether the test to check if the server is dissociated from the cloud, is run.

Example responses

The following table shows example responses for the health check APIs.
Table 2. Health check API response information
API type Response
Simple health check API
200
{
   "status" : "success"
}
The Management server is up and ready to receive requests.
409
{
   "status" : "failure"
}
There is an issue with the Management server, and it is not ready to receive requests.
Detailed health check API
200
{
   "isInServers": "true",
   "isInCluster": "unknown",
   "isCouchUp": "true",
   "isWritable": "unknown",
   "isReadable": "true",
   "isActive": "true",
   // Comment: "isCloudDissociated" and "dissociatedServers" are only available in version 5.0.8.3, and later
   "isCloudDissociated": "false",
   "dissociatedServers": [],
   // Comment: "isDissociated" is deprecated as of version 5.0.8.3
   "isDissociated": "false",
   "error": null
}
The Management server is up and ready to receive requests.
409
{
   "isInServers": "true",
   "isInCluster": "unknown",
   "isCouchUp": "true",
   "isWritable": "unknown",
   "isReadable": "true",
   "isActive": "true",
   // Comment: "isCloudDissociated" and "dissociatedServers" are only available in version 5.0.8.3, and later
   "isCloudDissociated": "true",
   "dissociatedServers": [
     "hostname_or_IP_address_of_dissociated_server_1",
     "hostname_or_IP_address_of_dissociated_server_2"
   ],
   // Comment: "isDissociated" is deprecated as of version 5.0.8.3
   "isDissociated": "false",
   "error": null
 }
There is an issue with the Management server, and it is not ready to receive requests.