diff --git a/en/docs/api-gateway/next/deployment/deployment-modes/kubernetes/kubernetes-standalone.md b/en/docs/api-gateway/next/deployment/deployment-modes/kubernetes/kubernetes-standalone.md index 3194f45e4..b5be3ff43 100644 --- a/en/docs/api-gateway/next/deployment/deployment-modes/kubernetes/kubernetes-standalone.md +++ b/en/docs/api-gateway/next/deployment/deployment-modes/kubernetes/kubernetes-standalone.md @@ -237,12 +237,13 @@ helm install ap-gateway oci://ghcr.io/wso2/api-platform/helm-charts/gateway \ ### Port-forward Gateway Controller Service ```bash -kubectl port-forward svc/ap-gateway-controller 9090:9090 +kubectl port-forward svc/ap-gateway-controller 9090:9090 9094:9094 ``` -### Verify gateway controller admin endpoint is running +### Verify the Gateway Controller's admin endpoint is running + ```bash -curl http://localhost:9094/api/admin/v0.9/health +curl http://localhost:9094/api/admin/v1/health ``` ### Deploy an API configuration diff --git a/en/docs/api-gateway/next/deployment/production-deployment/deploy-and-verify.md b/en/docs/api-gateway/next/deployment/production-deployment/deploy-and-verify.md index 6e6b5e986..f45a6bd8a 100644 --- a/en/docs/api-gateway/next/deployment/production-deployment/deploy-and-verify.md +++ b/en/docs/api-gateway/next/deployment/production-deployment/deploy-and-verify.md @@ -58,7 +58,7 @@ kubectl get svc -n ap-gateway ```bash kubectl exec -n ap-gateway deploy/ap-gateway-controller -- \ - wget -qO- http://localhost:9094/api/admin/v0.9/health + wget -qO- http://localhost:9094/api/admin/v1/health ``` ## Upgrade Procedure diff --git a/en/docs/api-gateway/next/setup/artifact-templating.md b/en/docs/api-gateway/next/setup/artifact-templating.md index 3cb891604..340737aed 100644 --- a/en/docs/api-gateway/next/setup/artifact-templating.md +++ b/en/docs/api-gateway/next/setup/artifact-templating.md @@ -117,3 +117,7 @@ In this example: - `ORDERS_BACKEND_URL` is optional — falls back to the default URL if not set. - `ORDERS_API_KEY` is required — the gateway will not start if it is missing, and the value is redacted in config dumps. - `DEPLOYMENT_ENV` is optional with a default of `production`. + +--- + +[← Setting Up the Database](./database-setup.md)  |  [Health Checks →](./health-checks.md) diff --git a/en/docs/api-gateway/next/setup/health-checks.md b/en/docs/api-gateway/next/setup/health-checks.md new file mode 100644 index 000000000..0cc6cd6bd --- /dev/null +++ b/en/docs/api-gateway/next/setup/health-checks.md @@ -0,0 +1,183 @@ +--- +title: "Health checks for the Gateway Controller and Gateway Runtime" +description: "Configure liveness and readiness health checks for the API Platform Gateway Controller, Router, and Policy Engine using the dedicated /_gateway-health endpoints, and wire them into Docker Compose or Kubernetes probes." +canonical_url: https://wso2.com/api-platform/docs/api-gateway/setup/health-checks/ +md_url: https://wso2.com/api-platform/docs/api-gateway/setup/health-checks.md +tags: + - api-gateway + - health-check + - deployment +author: WSO2 API Platform Documentation Team +last_updated: 2026-07-31 +content_type: "how-to" +--- + +# Health checks for the Gateway Controller and Gateway Runtime + +This guide is for developers and platform operators wiring liveness and readiness checks for the API Platform Gateway into Docker Compose or Kubernetes. The Gateway Controller and the Gateway Runtime each expose Hypertext Transfer Protocol (HTTP) endpoints that report whether that component is ready to handle traffic. + +The gateway has three health surfaces: + +- The **Gateway Controller** admin API, reachable at `/api/admin/v1/health`. +- The **Router**, reachable at `/_gateway-health/healthy` and `/_gateway-health/ready` on the same ports that serve API traffic. +- The **Policy Engine** admin API, reachable at `/health`. + +The Router and the Policy Engine each expose their own health endpoint inside the Gateway Runtime container. + +## Gateway Controller health endpoint + +The Gateway Controller exposes a health endpoint on its admin HTTP server: + +| Item | Value | +|------|-------| +| Path | `/api/admin/v1/health` | +| Legacy path | `/health` (deprecated) | +| Default port | `9094` | +| Method | `GET` | +| Healthy response | `200` with a JavaScript Object Notation (JSON) body: `{"status": "healthy", "timestamp": "..."}` | + +Test it directly with: + +```bash +curl http://localhost:9094/api/admin/v1/health +``` + +The Gateway Controller admin API is protected by an Internet Protocol (IP) allowlist and, when configured, Basic authentication. Both `/api/admin/v1/health` and the legacy `/health` are exempt from both checks, so Docker and Kubernetes probes can reach them without credentials. Every other admin path still requires an allowed IP and, if enabled, valid credentials. + +## Gateway Runtime health checks + +The Gateway Runtime container runs the Router and the Policy Engine, and each exposes its own health endpoint. + +### Router liveness and readiness + +The Router exposes two dedicated endpoints on its regular ingress listeners, so no separate admin port is involved: + +| Item | Value | +|------|-------| +| Liveness path | `/_gateway-health/healthy` | +| Readiness path | `/_gateway-health/ready` | +| Ports | `8080` (HTTP ingress) and `8443` (HTTPS ingress) | +| Method | `GET` | +| Healthy response | `200` with `{"status": "healthy"}` or `{"status": "ready"}` | + +```bash +curl http://localhost:8080/_gateway-health/healthy +curl -k https://localhost:8443/_gateway-health/ready +``` + +Both paths answer on both ports; the example above simply pairs liveness with the HTTP listener and readiness with the Hypertext Transfer Protocol Secure (HTTPS) listener. + +The path prefix `/_gateway-health` is reserved for the gateway's own liveness and readiness routes. No other route can use it. + +### Policy Engine health + +The Policy Engine admin server exposes its own health endpoint: + +| Item | Value | +|------|-------| +| Path | `/health` | +| Default port | `9002` | +| Method | `GET` | +| Healthy response | `200` with `{"status": "healthy", "timestamp": "..."}` | + +```bash +curl http://localhost:9002/health +``` + +The Policy Engine admin server has no Basic authentication layer, and `/health` bypasses even its IP allowlist, so probes always reach it. + +## Configuring health checks + +=== "Docker Compose" + + Add a `healthcheck:` block to each service, using `curl` against each component's health path. + + 1. For the `gateway-controller` service, point the `healthcheck` at the admin health path: + + ```yaml + services: + gateway-controller: + healthcheck: + test: ["CMD", "curl", "-f", "http://localhost:9094/api/admin/v1/health"] + interval: 10s + timeout: 3s + retries: 5 + start_period: 10s + ``` + + 2. For the `gateway-runtime` service, check both the Router's readiness path and the Policy Engine's health path in the same `healthcheck`, since the container isn't ready to handle traffic unless both processes report healthy: + + ```yaml + services: + gateway-runtime: + healthcheck: + test: ["CMD-SHELL", "curl -f http://localhost:8080/_gateway-health/ready && curl -f http://localhost:9002/health"] + interval: 10s + timeout: 3s + retries: 5 + start_period: 10s + ``` + +=== "Kubernetes" + + Configure a `readinessProbe` and a `livenessProbe` on each container. + + 1. For the Gateway Controller container, use an `httpGet` probe directly against its admin health path: + + ```yaml + spec: + template: + spec: + containers: + - name: gateway-controller + readinessProbe: + httpGet: + path: /api/admin/v1/health + port: 9094 + initialDelaySeconds: 5 + periodSeconds: 10 + livenessProbe: + httpGet: + path: /api/admin/v1/health + port: 9094 + initialDelaySeconds: 10 + periodSeconds: 15 + ``` + + 2. For the Gateway Runtime container, point the liveness probe at `/_gateway-health/healthy` on the HTTP listener: + + ```yaml + spec: + template: + spec: + containers: + - name: gateway-runtime + livenessProbe: + httpGet: + path: /_gateway-health/healthy + port: 8080 + initialDelaySeconds: 10 + periodSeconds: 15 + ``` + + 3. Point the readiness probe at both the Router's readiness path on the HTTPS listener and the Policy Engine's health path, since the Gateway Runtime container isn't ready to handle traffic unless both processes report healthy: + + ```yaml + spec: + template: + spec: + containers: + - name: gateway-runtime + readinessProbe: + exec: + command: + - sh + - -c + - curl -k -f https://localhost:8443/_gateway-health/ready && curl -f http://localhost:9002/health + initialDelaySeconds: 5 + periodSeconds: 10 + ``` + +--- + +[← Artifact Templating](./artifact-templating.md)  |  [Configuring Timeouts →](../resiliency/timeouts.md) diff --git a/en/docs/llms.txt b/en/docs/llms.txt index 8115b83cd..956528758 100644 --- a/en/docs/llms.txt +++ b/en/docs/llms.txt @@ -260,6 +260,7 @@ - [Setting Up the Database](https://wso2.com/api-platform/docs/api-gateway/setup/database-setup.md): Create the database and apply the Gateway Controller schema scripts for PostgreSQL or SQL Server before starting the gateway - [Storage and Backends](https://wso2.com/api-platform/docs/api-gateway/setup/storage-and-backends.md): Configure PostgreSQL as the Gateway Controller storage backend and Redis for distributed rate limiting - [Artifact Templating](https://wso2.com/api-platform/docs/api-gateway/setup/artifact-templating.md): Use Go text template expressions in API Platform Gateway YAML artifacts to inject environment variables and dynamic values at startup +- [Health Checks](https://wso2.com/api-platform/docs/api-gateway/setup/health-checks.md): Configure liveness and readiness health checks for the Gateway Controller, Router, and Policy Engine, and wire them into Docker Compose or Kubernetes probes - [Upstream Timeouts](https://wso2.com/api-platform/docs/api-gateway/setup/upstream-timeouts.md): Configure the upstream TCP connection timeout in API Platform Gateway to protect against slow or unreachable backend services - [API Gateway Policies Overview](https://wso2.com/api-platform/docs/api-gateway/policies/overview.md): Overview of the policy framework for the standalone gateway - [Writing a Custom Policy](https://wso2.com/api-platform/docs/api-gateway/policies/custom-policies/writing-a-custom-policy.md): Write a custom policy for API Platform Gateway using the Go SDK: implement request and response hooks in the policy chain diff --git a/en/mkdocs.yml b/en/mkdocs.yml index ff30f8059..2b9119be1 100644 --- a/en/mkdocs.yml +++ b/en/mkdocs.yml @@ -343,6 +343,7 @@ nav: - Configuration & Interpolation: api-gateway/next/setup/configuration.md - Setting Up the Database: api-gateway/next/setup/database-setup.md - Artifact Templating: api-gateway/next/setup/artifact-templating.md + - Health Checks: api-gateway/next/setup/health-checks.md - Resiliency: - Timeouts: api-gateway/next/resiliency/timeouts.md - Policies: