Health Check

Learn how to create, configure, and implement health check policies for your HTTP and gRPC API Proxies using NGINX Management Suite API Connectivity Manager.

Overview

In API Connectivity Manager, you can apply policies to an API Gateway to further enhance their configuration to meet your requirements.

Policies added at the proxy level are applied to all routes within that proxy.

For an overview of the different policy types and available policies, refer to the consult the Learn about Policies topic.

About the Policy

API Connectivity Manager can configure your API Proxies to continually test your backend service targets (upstream servers), avoid the servers that have failed, and gracefully add the recovered services to a load-balanced group. This continuous testing is also known as “Active Health Checks,” whereas “Passive Health Checks” monitor transactions as they occur.

More information on NGINX health checks can be found at:

Intended Audience

This guide is intended for API Owners — the individuals or teams who are responsible for designing, creating, and maintaining APIs.


HTTP Health Checks

Before You Begin

To complete the steps in this guide, you need the following:

Policy Settings

Field Datatype Possible Values
Description
Required Default value
targetBackendPolicyLabel string Example: default This field is used to target a specific backend by label. No default
transportProtocol string One of ["http"] The transport protocol used by the service. Only http is supported for now. No http
isMandatory bool true/false Requires every newly added server to pass all configured health checks before NGINX Plus sends traffic to it. No false
persistent bool true/false Determines whether previous state is remembered after reloading configuration. No false
port int In range 1-65535 The port on the service that will provide the health check. No N/A
interval int Integer (Max 2147483647) The length of time between each health check sent from Nginx to the respective service. No 5
unhealthyThreshold int Integer (Max 2147483647) Denotes the number of failed checks before the service is considered unhealthy. No 1
healthyThreshold int Integer (Max 2147483647) Denotes the number of successful checks before the service is considered healthy. No 1
http
.uriPath
string Example: /health The URI used for the health check and is appended to the server domain name or IP address No /
http
.responseMatch
.statusCode
.exact
int In range 100-599 List of specific status codes to match against No N/A
http
.responseMatch
.statusCode
.range
string Example: ["200-399"] List of status code ranges to match against No N/A
http
.responseMatch
.header
.name
string Example: header-name Any valid header value from the response Yes N/A
http
.responseMatch
.header
.value
string Example: header-value Any valid header name from the response Yes N/A
http
.responseMatch
.header
.condition
string Regex: ^([=!~]|!~)$ The matching operator for the header. Uses NGINX Health Check match directive syntax Yes N/A
http
.responseMatch
.body
.requiredVariable
string Example: jsonFieldKey Field in json of body to match against No N/A
http
.responseMatch
.body
.value
string Example: jsonFieldValue Any valid body content to be matched against Yes N/A
http
.responseMatch
.body
.condition
string Regex: ^!?~$ The matching operator for the body. Uses NGINX Health Check match directive syntax Yes N/A
connectTimeout string Example: 60s Sets a timeout for establishing a connection with a proxied server. Uses NGINX time measurement syntax No 1s
readTimeout string Example: 60s Sets a timeout for reading a response from the proxied server. Uses NGINX time measurement syntax No 1s

Create an HTTP Health Check Policy

See Also:
You can use tools such as curl or Postman to interact with the API Connectivity Manager REST API. The API URL follows the format https://<NMS_FQDN>/api/acm/<API_VERSION> and must include authentication information with each call. For more information about authentication options, please refer to the API Overview.

To create an HTTP health check policy, send an HTTP POST to the Proxies endpoint.

Method Endpoint
POST /services/workspaces/{SERVICE_WORKSPACE_NAME}/proxies
JSON request
{
  "policies": {
    "backend-health-check": [
      {
        "action": {
          "targetBackendPolicyLabel": "default",
          "transportProtocol": "http",
          "isMandatory": true,
          "persistent": true,
          "port": 8080,
          "interval": 5,
          "unhealthyThreshold": 3,
          "healthyThreshold": 2,
          "http": {
            "uriPath": "/health_check",
            "responseMatch": {
              "statusCode": {
                "range": [
                  "200-399"
                ]
              },
              "header": {
                "name": "some-header",
                "value": "ok",
                "condition": "="
              },
              "body": {
                "requiredVariable": "jsonField",
                "value": "some-response-body",
                "condition": "~"
              }
            }
          },
          "connectTimeout": "10s",
          "readTimeout": "10s"
        }
      }
    ]
  }
}

To create a Health Check policy using the web interface:

  1. In a web browser, go to the FQDN for your NGINX Management Suite host and log in. Then, from the Launchpad menu, select API Connectivity Manager.

  2. On the left menu, select Services.

  3. Select a workspace in the list that contains the API Proxy you want to update.

  4. On the workspace overview page, on the API Proxies tab, locate the API Proxy you want to update. Select the Actions menu (represented by an ellipsis, ...), then select Edit Proxy.

  5. On the left-side API Proxy menu, select Policies.

  6. On the Advanced > Policies page, on the API Proxy tab, locate the Backend Health Check policy. Select the Actions menu (represented by an ellipsis, ...), then select Add Policy.

  7. Complete the necessary fields:

    • Apply the policy to: Specify the label that was assigned to the backend service if it’s different from the default value default.
    • Transport Protocol: Specify the transport protocol of the health check. Currently, only HTTP is supported.
    • Is Mandatory: Toggle the switch to on if every new service target (server) must pass all configured health checks before NGINX Plus sends traffic to it.
    • Port: If the health check needs to be conducted on a port other than the one specified for the backend service targets, specify the port to use.
    • Interval: The length of time between each health check sent from NGINX Plus to the backend service targets.
    • Unhealthy Threshold: Denotes the number of failed checks before the service is considered unhealthy.
    • Health Threshold: Denotes the number of successful checks before the service is considered healthy.
    • URI Path: The endpoint (URI) that NGINX Plus uses for the health check requests.
    • Status Code Exact: The list of specific HTTP status codes to match against in the backend response.
    • Status Code Range: The list of HTTP status code ranges to match against in the backend response.
    • Header Name: The name of the header to use in the backend response matching.
    • Header Condition: The operator used when checking the header value. Refer to the NGINX match directive documentation for specifics.
    • Header Value: The header value to use in the backend response matching.
    • Body Required Variable: The field in the JSON of the backend response body to match against.
    • Body Condition: The operator used when checking the body value. Refer to the NGINX match directive documentation for specifics.
    • Body Value: The body value to use in the backend response matching.
    • Connection Timeout: Sets a timeout for establishing a connection with a proxied server. Follows NGINX configuration file measurement units syntax.
    • Read Timeout: Sets a timeout for reading a response from the proxied server. Follows NGINX configuration file measurement units syntax.
  8. Select Add to apply the Health Check policy to the API Proxy. Then select Save & Publish to deploy the configuration to the API Proxy.

Verify the Policy

Confirm that the policy has been set up and configured correctly by taking these steps:

  • Check that your backend service targets (upstream servers) are receiving health check endpoint calls.
  • When isMandatory is set to true, verify that your backend service targets are not receiving proxied traffic until they clear the health checks.
  • When persistent is set to true, the state and behavior for interval, unhealthyThreshold, healthyThreshold, and timeout-related parameters should be preserved between subsequent deployments of API proxies and environments.

gRPC Health Checks

Before You Begin

To complete the steps in this guide, you need the following:

Policy Settings

Field Datatype Possible Values Description Required Default value
targetBackendLabel string Example: default This field is used to target a specific backend by label. No default
mandatory bool true/false Requires every newly added server to pass all configured health checks before NGINX Plus sends traffic to it. No false
persistent bool true/false Determines whether previous state is remembered after reloading configuration. No false
port int In range 1-65535 The port on the service that will provide the health check. No N/A
interval int Integer (Max 2147483647) The length of time between each health check sent from Nginx to the respective service. No N/A
passes int Integer (Max 2147483647) Denotes the number of successful checks before the service is considered healthy. No N/A
fails int Integer (Max 2147483647) Denotes the number of unsuccessful checks before the service is considered unhealthy. No N/A
grpc
.service
string Example: RouteGuide Defines the target GRPC service to be used for this health check No N/A
grpc
.status
int Example: 12 The expected GRPC status code return code from the upstream gRPC backend to conclude that the health check was successful No N/A
connectTimeout string Example: 60s Sets a timeout for establishing a connection with a proxied server. Uses NGINX time measurement syntax No 1s
readTimeout string Example: 60s Sets a timeout for reading a response from the proxied server. Uses NGINX time measurement syntax No 1s

Create a gRPC Health Check Policy

See Also:
You can use tools such as curl or Postman to interact with the API Connectivity Manager REST API. The API URL follows the format https://<NMS_FQDN>/api/acm/<API_VERSION> and must include authentication information with each call. For more information about authentication options, please refer to the API Overview.

To create a gRPC health check policy, send an HTTP POST to the Proxies endpoint.

Method Endpoint
POST /services/workspaces/<SERVICE_WORKSPACE_NAME>/proxies
JSON request
{
  "policies": {
    "grpc-backend-health-check": [
      {
        "action": {
          "mandatory": true,
          "persistent": true,
          "port": 84,
          "interval": 7,
          "fails": 3,
          "passes": 5,
          "connectTimeout": "6s",
          "readTimeout": "5s",
          "grpc": {
            "status": 12
          }
        }
      }
    ]
  }
}

To create a gRPC Health Check policy using the web interface:

  1. In a web browser, go to the FQDN for your NGINX Management Suite host and log in. Then, from the Launchpad menu, select API Connectivity Manager.

  2. On the left menu, select Services.

  3. Select a workspace in the list that contains the API Proxy you want to update.

  4. On the workspace overview page, on the API Proxies tab, locate the API Proxy you want to update. Select the Actions menu (represented by an ellipsis, ...), then select Edit Proxy.

  5. On the left-side API Proxy menu, select Policies.

  6. On the Advanced > Policies page, on the API Proxy tab, locate the gRPC Backend Health Check policy. Select the Actions menu (represented by an ellipsis, ...), then select Add Policy.

  7. Complete the necessary fields:

    • Apply the policy to: Provide the label that was assigned to a Backend Service if it is different from the default value `default
    • Is Mandatory: Toggle the switch to on if every new service target (server) must pass all configured health checks before NGINX Plus sends traffic to it.
    • Port: If the health check needs to be conducted on a port other than the one specified for the backend service targets, specify the port to use.
    • Interval: The length of time between each health check sent from NGINX Plus to the backend service targets.
    • The gRPC setting will determine which health check service will be contacted by NGINX and which status code will be expected.
  8. Select Add to apply the Health Check policy to the API Proxy. Then select Save & Publish to deploy the configuration to the API Proxy.

Verify the Policy

Confirm that the policy has been set up and configured correctly by taking these steps:

  • Check that your backend service targets (upstream servers) are receiving health check endpoint calls. You may also find the tools grpcurl and grpc-health-probe helpful for debugging.
  • When mandatory is set to true, verify that your backend service targets are not receiving proxied traffic until they clear the health checks.
  • When persistent is set to true, state and behavior for interval, passes, fails, and timeout related parameters should be preserved between subsequent deployments of API Proxies and Environments.