Readiness Check

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 instances. When Kong 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.

Prerequisites

Kong Gateway
A basic understanding of Kong Gateway configuration and deployment modes (traditional, DB-less, and hybrid)

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 instance is ready or not.

Traditional mode

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

Successful connection to the database
All Kong workers are ready to route requests
All routes and services have their plugins ready to process requests

Hybrid mode (`data_plane` role) or DB-less mode

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

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

Hybrid mode (`control_plane` role)

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

Successful connection to the database

Enabling the Status endpoint

In order 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:

status_listen = 0.0.0.0:8100

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:

# Replace `<status-api-host>` with the appropriate host for
# your Status API server, including the port number

curl -i <status-api-host>/status/ready

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

HTTP/1.1 200 OK
Date: Thu, 04 May 2023 22:00:52 GMT
Content-Type: application/json; charset=utf-8
Connection: keep-alive
Access-Control-Allow-Origin: *
Content-Length: 19
X-Kong-Admin-Latency: 3
Server: kong/3.3.0

{
  "message": "ready"
}

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

HTTP/1.1 503 Service Temporarily Unavailable
Date: Thu, 04 May 2023 22:01:11 GMT
Content-Type: application/json; charset=utf-8
Connection: keep-alive
Access-Control-Allow-Origin: *
Content-Length: 43
X-Kong-Admin-Latency: 3
Server: kong/3.3.0

{
  "message": "failed to connect to database"
}

HTTP/1.1 503 Service Temporarily Unavailable
Date: Thu, 04 May 2023 22:06:58 GMT
Content-Type: application/json; charset=utf-8
Connection: keep-alive
Access-Control-Allow-Origin: *
Content-Length: 70
X-Kong-Admin-Latency: 16
Server: kong/3.3.0

{
  "message": "no configuration available (empty configuration present)"
}

Updating Readiness Probes

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:

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