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
- Whether the server is considered to be in an active state.
- Whether the server is able to read documents from the configuration database.
- Whether the server is able to write documents to the configuration database.
- Whether the server is able to use the CouchDB database.
- Whether the server is a member of a management service with the provided display name.
- Whether the server is in the list of servers.
- 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.
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.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.
- 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
, or5XX
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.
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.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.
'cmc/account_name'
. An authentication error occurs
if you do not apply the 'cmc/'
prefix.- 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
, or5XX
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.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. |
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.API type | Response |
---|---|
Simple health check API |
|
Detailed health check API |
|