Reliable Gateway Health Checks with a Mock API

By default, Tyk Gateway health checks often rely on the /hello endpoint. However, this endpoint always returns a 200 OK, even if critical components like Redis or API definitions fail to load. This can delay detection and recovery of unhealthy Gateway pods.

This article outlines a simple but effective reliability improvement: configure a Dummy/Mock API, and point your Kubernetes liveness and readiness probes to it instead. This allows Kubernetes to restart the pod if the Gateway fails to load APIs properly.

Health Checks in the Helm Chart

The Tyk Charts supports customization of both liveness and readiness probes via the gateway.livenessProbe and gateway.readinessProbe fields in your values.yaml file.

We recommend separating health checks based on intent:

gateway:
  livenessProbe:
    httpGet:
      scheme: "HTTP{{ if .Values.global.tls.gateway }}S{{ end }}"
      path: /hello
      port: 8080
    initialDelaySeconds: 10
    periodSeconds: 5
    timeoutSeconds: 3
    failureThreshold: 3

  readinessProbe:
    httpGet:
      scheme: "HTTP{{ if .Values.global.tls.gateway }}S{{ end }}"
      path: /h/
      port: 8080
    initialDelaySeconds: 5
    periodSeconds: 10
    timeoutSeconds: 3
    failureThreshold: 3
    

Replace /h/ with the actual path of your dummy health check API.

Why /hello May Not Be Enough

The /hello endpoint is always available if the Gateway is running, regardless of whether APIs have loaded or Redis is connected.

• It always returns a 200 OK, regardless of internal failures
• While it includes internal status in the response body, Kubernetes probes typically check status codes, not content
• This can result in false positives, where a pod appears healthy to Kubernetes even though it's not functionally ready

Better Approach: Use a Dummy API Endpoint

Create a dummy API that listens on a short path like /h/ and returns a static mock response. This endpoint will only return a 200 OK if the Gateway has successfully loaded its API definitions — making it a much more reliable indicator of readiness than /hello.

Tip:
To slightly increase the confidence in full system readiness, you can attach a plugin bundle to this dummy API. While not a strong guarantee, the fact that the bundle loads successfully indirectly confirms that other bundle-based APIs are more likely to be operational.

Mock API Guidelines for Reliable Probes

The Tyk Gateway loads APIs in a specific order based on domain and path length. See here.
To improve the chances that your dummy API loads last, and therefore reflects successful loading of other APIs:

• Avoid setting a custom domain on this one, if you can help it
• Use a shorter listen path than your other APIs; /h/ is a solid choice

Sample API Definitions

Feel free to adjust.

Classic:

{
  "name": "Gateway Health Check",
  "use_keyless": true,
  "active": true,
  "proxy": {
    "listen_path": "/h/",
    "target_url": "http://example.com",
    "strip_listen_path": true
  },
  "custom_middleware_bundle": "health_check_bundle.zip",
  "version_data": {
    "not_versioned": true,
    "versions": {
      "Default": {
        "name": "Default",
        "use_extended_paths": true,
        "extended_paths": {
          "ignored": [
            {
              "path": "/",
              "method_actions": {
                "GET": {
                  "action": "no_action",
                  "code": 200,
                  "headers": {},
                  "data": ""
                }
              }
            }
          ],
          "mock_response": [
            {
              "path": "/",
              "method": "GET",
              "code": 200,
              "body": "Gateway is healthy",
              "headers": {
                "Content-Type": "text/plain"
              }
            }
          ]
        }
      }
    }
  }
}

K8s Custom Resource Definition.

apiVersion: tyk.tyk.io/v1alpha1
kind: ApiDefinition
metadata:
  name: gateway-health-check
  namespace: tyk
spec:
  name: "Gateway Health Check"
  use_keyless: true
  active: true
  protocol: http
  proxy:
    target_url: "http://example.com"
    listen_path: "/h/"
    strip_listen_path: true
  custom_middleware_bundle: "health_check_bundle.zip"
  version_data:
    not_versioned: true
    default:
      name: "Default"
      use_extended_paths: true
      extended_paths:
        ignored:
          - path: "/"
            method_actions:
              GET:
                action: "no_action"
                code: 200
        mock_response:
          - path: "/"
            method: "GET"
            code: 200
            body: "Gateway is healthy"
            headers:
              Content-Type: "text/plain"

OAS:

openapi: 3.0.3
info:
  title: Gateway Health Check
  version: 1.0.0
servers:
  - url: http://example.com/h/
paths:
  /:
    get:
      operationId: healthCheck
      responses:
        '200':
          description: Healthy response
          content:
            text/plain:
              example: Gateway is healthy
x-tyk-api-gateway:
  info:
    name: Gateway Health Check
    state:
      active: true
  server:
    listenPath:
      value: /h/
      strip: true
  upstream:
    url: http://example.com
  middleware:
    global:
      pluginConfig:
        bundle:
         enabled: true
         path: health_check_bundle.zip
    operations:
      healthCheck:
        mockResponse:
          enabled: true
          code: 200
          body: Gateway is healthy
          headers:
            - name: Content-Type
              value: text/plain
        ignoreAuthentication:
          enabled: true