Add health check documentation for the Gateway Controller and Gateway Runtime #413
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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." | ||
|
coderabbitai[bot] marked this conversation as resolved.
|
||
| 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`. | ||
|
coderabbitai[bot] marked this conversation as resolved.
|
||
|
|
||
| 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. | ||
|
There was a problem hiding this comment. 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win Use active voice in the endpoint explanations. Line 45 uses passive constructions for API protection and health-endpoint exemptions. Line 70 uses passive wording for the reserved path prefix. Rewrite these sentences with the responsible component or configuration as the subject. As per path instructions, Markdown under Also applies to: 70-70 🤖 Prompt for AI AgentsSource: Path instructions |
||
|
|
||
| ## 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. | ||
|
There was a problem hiding this comment. 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win Split the long probe instructions. Line 68 has 26 words. Lines 108 and 163 exceed 26 words. Split each sentence into shorter sentences. Place the condition before the dependent action at Lines 108 and 163. As per path instructions, documentation uses sentences with fewer than 26 words and places conditional clauses before their consequences. Also applies to: 108-108, 163-163 🤖 Prompt for AI AgentsSource: Path instructions |
||
|
|
||
| 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 | ||
| ``` | ||
|
coderabbitai[bot] marked this conversation as resolved.
|
||
|
|
||
| 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) | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.