You are browsing documentation for an older version. See the latest documentation here.

Health Check Probes

This tutorial guides you through the process of using the node readiness endpoint, which provides a reliable way to determine if Kong Gateway is ready to serve user requests.

The readiness check endpoint returns a 200 OK response when Kong Gateway is ready, or a 503 Service Temporarily Unavailable response when it’s not. This is useful for load balancers and other tools that need to monitor the readiness of Kong Gateway instances. When Kong Gateway is not ready, the endpoint responds back with a message field with the reason for unreadiness. This can be helpful to debug situations where the user expects that the node should be ready but is not.

Note: The readiness endpoint does not return detailed information about the node status.

Types of health checks

For each Kong Gateway node, there are two distinct health checks (also known as “probes”):

  • Liveness: The /status endpoint responds with a 200 OK status if Kong Gateway is running. The request will fail either with a 500 Internal Server Error or no response if Kong Gateway is not running. You can send a GET request to check the liveness of your Kong Gateway instance:

    1. # Replace localhost:8100 with the appropriate host and port for
    2. # your Status API server
    4. curl -i http://localhost:8100/status

  • Readiness: The /status/ready endpoint responds with a 200 OK status if Kong Gateway has successfully loaded a valid configuration and is ready to proxy traffic. The request will fail either with a 503 Service Temporarily Unavailable or no response if Kong Gateway is not ready to proxy traffic yet. You can send a GET request to check the readiness of your Kong Gateway instance:

    1. # Replace localhost:8100 with the appropriate host and port for
    2. # your Status API server
    4. curl -i http://localhost:8100/status/ready

These two types of health checks for Kong Gateway are modeled on how Kubernetes defines health check probes.

We strongly recommend that a component (that is, a load balancer) perform the readiness health check before sending traffic. This ensures that a Kong Gateway node has not only successfully started up but has also finished loading up the configuration and is ready to receive proxy traffic.

The liveness health check may return a 200 OK response before the readiness health check does. Even if Kong Gateway is running, it may still be loading the full configuration, which means it is live but not ready. If a component only monitors the liveness probe to decide when to send traffic to Kong Gateway, there will be a short period of time where requests will be met with a 404 Not Found response before the Kong Gateway is ready to proxy traffic. We recommend using the readiness probe over the liveness probe, especially in production environments.

Understanding the node readiness endpoint

Before diving into the steps, it’s important to understand the purpose of the node readiness endpoint and how it determines whether a Kong Gateway instance is ready or not. The endpoint acts differently depending on the node type.

Traditional mode

Hybrid mode (data plane role) or DB-less mode

Hybrid mode (control plane role)

In traditional mode, the endpoint returns 200 OK when all of the following conditions are met:

  1. Successful connection to the database
  2. All Kong Gateway workers are ready to route requests
  3. All routes and services have their plugins ready to process requests

In hybrid mode (data_plane role) or DB-less mode, the endpoint returns 200 OK when the following conditions are met:

  1. Kong Gateway has loaded a valid and non-empty config (kong.yaml)
  2. All Kong Gateway workers are ready to route requests
  3. All routes and services have their plugins ready to process requests

In hybrid mode (control_plane role), this endpoint returns 200 OK when the following condition is met:

  1. Successful connection to the database

Enabling the node readiness endpoint

To use the node readiness endpoint, make sure that you have enabled the Status API server (disabled by default) via the status_listen configuration parameter.

Example kong.conf:

  1. status_listen = 0.0.0.0:8100

Note: Readiness probes should be used on every node within the cluster, including standalone, control plane, and data plane nodes. Checking only one node in a cluster is insufficient.

Using the node readiness endpoint

Once you’ve enabled the node readiness endpoint, you can send a GET request to check the readiness of your Kong Gateway instance:

  1. # Replace localhost:8100 with the appropriate host and port for
  2. # your Status API server
  4. curl -i http://localhost:8100/status/ready

If the response code is 200, the Kong Gateway instance is ready to serve requests:

  1. HTTP/1.1 200 OK
  2. Date: Thu, 04 May 2023 22:00:52 GMT
  3. Content-Type: application/json; charset=utf-8
  4. Connection: keep-alive
  5. Access-Control-Allow-Origin: *
  6. Content-Length: 19
  7. X-Kong-Admin-Latency: 3
  8. Server: kong/3.3.0
  10. {
  11.   "message": "ready"
  12. }

If the response code is 503, the Kong Gateway instance is unhealthy and/or not yet ready to serve requests:

  1. HTTP/1.1 503 Service Temporarily Unavailable
  2. Date: Thu, 04 May 2023 22:01:11 GMT
  3. Content-Type: application/json; charset=utf-8
  4. Connection: keep-alive
  5. Access-Control-Allow-Origin: *
  6. Content-Length: 43
  7. X-Kong-Admin-Latency: 3
  8. Server: kong/3.3.0
  10. {
  11.   "message": "failed to connect to database"
  12. }
  1. HTTP/1.1 503 Service Temporarily Unavailable
  2. Date: Thu, 04 May 2023 22:06:58 GMT
  3. Content-Type: application/json; charset=utf-8
  4. Connection: keep-alive
  5. Access-Control-Allow-Origin: *
  6. Content-Length: 70
  7. X-Kong-Admin-Latency: 16
  8. Server: kong/3.3.0
  10. {
  11.   "message": "no configuration available (empty configuration present)"
  12. }

Using readiness probes in Kubernetes

If you’re using Kubernetes or Helm, you may need to update the readiness probe configuration to use the new node readiness endpoint. Modify the readinessProbe section in your configuration file to look like this:

  1. readinessProbe:
  2.     httpGet:
  3.         path: /status/ready
  4.         # Make sure to replace the port number with the one you
  5.         # configured for the Status API Server.
  6.         port: 8100
  7.     initialDelaySeconds: 10
  8.     periodSeconds: 5

Note: Failure to set an initialDelaySeconds may result in Kong Gateway entering a crash loop, as it requires a short time to fully load the configuration. The time to delay can depend on the size of the configuration.

Using a readiness check in version 3.2 or lower

The /status/ready endpoint was added in version 3.3, so prior versions don’t benefit from this built-in readiness endpoint. We recommend the following workaround for those versions:

  1. Configure a new route in Kong Gateway with the path uniquely set for this purpose. This route doesn’t require a service.

    For example, you could use the path /health/ready.

  2. Configure the Request Termination plugin to respond to requests on that route with a HTTP 200 status code.

Note: In this workaround, the port to send health check requests to is the proxy port (8000 & 8443 by default) instead of the status API port.

What isn’t covered by health checks?

A health check probe doesn’t take the following into account:

  • If Kong Gateway is performing optimally or not
  • If Kong Gateway is throwing intermittent failures for any reason
  • If Kong Gateway is throwing errors due to third-party systems like DNS, cloud provider outages, network failures, and so on
  • If any upstream services are throwing errors or responding too slowly

See also

For more information on Kong Gateway and related topics, check out the following resources: