Add health check documentation for the Gateway Controller and Gateway Runtime - #413
Add health check documentation for the Gateway Controller and Gateway Runtime#413tharindu1st wants to merge 1 commit into
Conversation
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughAdded API Gateway health-check documentation for versions ChangesHealth checks documentation
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 8
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@en/docs/api-gateway/next/setup/health-checks.md`:
- Line 17: Update the introductory sentence in the health-checks guide to
replace the ambiguous “they’re ready” wording with an explicit component
subject, and spell out “HTTP” as “Hypertext Transfer Protocol (HTTP)” at its
first use.
- Line 2: Update the page title and corresponding H1 in the health-check
documentation to use sentence case: change “Health Checks” to “Health checks”
while preserving “Gateway Controller” and “Gateway Runtime” as component names.
- Around line 89-148: The “Configuring health checks” section needs an ordered
procedure under both the Docker Compose and Kubernetes tabs. Add numbered steps
describing each configuration action, and place each existing YAML block
immediately after the step that introduces it while preserving the current
health paths and probe settings.
- Around line 105-111: Update the gateway-runtime health checks in the Compose
and Kubernetes examples to account for Policy Engine health, either by probing
both Router and Policy Engine readiness or by explicitly documenting that Router
readiness includes the Policy Engine dependency. Keep the existing health-check
settings unchanged apart from this dependency coverage.
- Line 37: Update the health-checks documentation to define JSON, IP, and HTTPS
at their first occurrences, and replace every “basic auth” or “basic-auth”
reference with “Basic authentication.” Apply the terminology consistently across
the referenced sections.
- Around line 19-23: Update the Gateway Controller entry in the “three health
surfaces” overview to use the current `/api/admin/v1/health` path instead of
`/health`, matching the endpoint table and deprecation guidance; leave the
Router and Policy Engine entries unchanged.
- Line 3: Shorten the frontmatter description to fewer than 158 characters and
accurately distinguish the health-check endpoints: Controller and Policy Engine
use /health, while Router uses /_gateway-health.
- Around line 35-42: Resolve the health-check documentation mismatch by
comparing the version-matched Controller deployment configuration, then align
the port and endpoint path across health-checks.md, quick-start examples,
deploy-and-verify.md, and Kubernetes standalone examples. Preserve a documented
distinction only if the configurations genuinely use different health endpoints.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 73f5a5ce-584f-43c6-aaa2-6ed76d71a89f
📒 Files selected for processing (3)
en/docs/api-gateway/next/setup/artifact-templating.mden/docs/api-gateway/next/setup/health-checks.mden/mkdocs.yml
|
Note GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer. |
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In
`@en/docs/api-gateway/next/deployment/deployment-modes/kubernetes/kubernetes-standalone.md`:
- Line 245: Update the Kubernetes standalone health-check instructions around
the curl command to ensure port 9094 is reachable: either forward both 9090 and
9094 for the ap-gateway-controller service, or replace the local curl with the
established in-pod execution command from deploy-and-verify.md.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 7c417d02-5aa3-4308-b935-991ac27cf1be
📒 Files selected for processing (5)
en/docs/api-gateway/next/deployment/deployment-modes/kubernetes/kubernetes-standalone.mden/docs/api-gateway/next/deployment/production-deployment/deploy-and-verify.mden/docs/api-gateway/next/setup/artifact-templating.mden/docs/api-gateway/next/setup/health-checks.mden/mkdocs.yml
|
@coderabbitai review and approve |
|
✅ Action performedComments resolved and changes approved. Review finished.
|
|
Note GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer. |
There was a problem hiding this comment.
Actionable comments posted: 2
♻️ Duplicate comments (1)
en/docs/api-gateway/next/setup/health-checks.md (1)
3-3: 🎯 Functional Correctness | 🟡 MinorCorrect the page description.
The description exceeds 158 characters and incorrectly implies that all components use
/_gateway-health. The Gateway Controller uses/api/admin/v1/health, and the Policy Engine uses/health.Proposed fix
-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." +description: "Configure liveness and readiness probes for the Gateway Controller, Router, and Policy Engine in Docker Compose or Kubernetes."As per path instructions, the description must be shorter than 158 characters and accurately summarize the page.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@en/docs/api-gateway/next/setup/health-checks.md` at line 3, Update the page frontmatter description to fewer than 158 characters, accurately distinguishing the Gateway Controller endpoint (/api/admin/v1/health), Policy Engine endpoint (/health), and Router health checks without implying they all use /_gateway-health.Source: Path instructions
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In
`@en/docs/api-gateway/next/deployment/deployment-modes/kubernetes/kubernetes-standalone.md`:
- Around line 243-245: Update the “Verify gateway controller admin endpoint is
running” heading to a clear sentence-case title using the documented component
name and possessive phrasing, then add a blank line before the following fenced
bash block to satisfy Markdown spacing rules.
In `@en/docs/api-gateway/next/setup/health-checks.md`:
- Around line 127-140: Update the readinessProbe and livenessProbe examples in
the health-check documentation to be self-contained Kubernetes YAML, including
the surrounding spec.template.spec.containers structure and correct indentation
showing where each probe belongs; apply the same fix to the additional probe
example.
---
Duplicate comments:
In `@en/docs/api-gateway/next/setup/health-checks.md`:
- Line 3: Update the page frontmatter description to fewer than 158 characters,
accurately distinguishing the Gateway Controller endpoint
(/api/admin/v1/health), Policy Engine endpoint (/health), and Router health
checks without implying they all use /_gateway-health.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 4aa57217-a3ca-4694-a225-2606e8bc2dc3
📒 Files selected for processing (6)
en/docs/api-gateway/next/deployment/deployment-modes/kubernetes/kubernetes-standalone.mden/docs/api-gateway/next/deployment/production-deployment/deploy-and-verify.mden/docs/api-gateway/next/setup/artifact-templating.mden/docs/api-gateway/next/setup/health-checks.mden/docs/llms.txten/mkdocs.yml
|
Note GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer. |
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@en/docs/api-gateway/next/setup/health-checks.md`:
- Line 68: Shorten the probe instruction sentences at the documented lines to
fewer than 26 words each. Split the sentence around the “Both paths”
explanation, and at the instructions near the liveness/readiness examples, place
each condition before the action it controls while preserving the existing
meaning.
- Line 45: Rewrite the endpoint explanations in the health-checks documentation
using active present-tense voice: make the Gateway Controller or its
configuration the subject when describing IP allowlisting, Basic authentication,
and exemptions for /api/admin/v1/health and /health, and make the responsible
routing component or configuration the subject of the reserved path-prefix
sentence. Preserve the documented access behavior for health endpoints and all
other admin paths.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 4b6fddde-6013-4b6f-b2bb-3b938b46667f
📒 Files selected for processing (6)
en/docs/api-gateway/next/deployment/deployment-modes/kubernetes/kubernetes-standalone.mden/docs/api-gateway/next/deployment/production-deployment/deploy-and-verify.mden/docs/api-gateway/next/setup/artifact-templating.mden/docs/api-gateway/next/setup/health-checks.mden/docs/llms.txten/mkdocs.yml
|
Note GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer. |
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In
`@en/docs/api-gateway/next/deployment/deployment-modes/kubernetes/kubernetes-standalone.md`:
- Line 246: Update the Kubernetes standalone verification curl command for
/api/admin/v1/health to include the --fail option, ensuring HTTP 4xx and 5xx
responses cause the command to exit unsuccessfully.
In `@en/docs/api-gateway/next/setup/health-checks.md`:
- Around line 59-68: Define “Hypertext Transfer Protocol Secure (HTTPS)” in the
Ports table before the acronym appears elsewhere, then use HTTPS in the
explanatory sentence. Apply this same acronym-ordering change in
en/docs/api-gateway/next/setup/health-checks.md lines 59-68 and
en/docs/api-gateway/1.2.0/setup/health-checks.md lines 59-68.
- Line 3: Shorten the description at
en/docs/api-gateway/next/setup/health-checks.md:3 and
en/docs/api-gateway/1.2.0/setup/health-checks.md:3 to the same text under 158
characters, naming the Gateway Controller, Router, Policy Engine, Docker
Compose, and Kubernetes without assigning a shared /_gateway-health endpoint to
every component.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: d80fb78b-23a4-4792-a343-c1a2849ec538
📒 Files selected for processing (8)
en/docs/api-gateway/1.2.0/setup/artifact-templating.mden/docs/api-gateway/1.2.0/setup/health-checks.mden/docs/api-gateway/next/deployment/deployment-modes/kubernetes/kubernetes-standalone.mden/docs/api-gateway/next/deployment/production-deployment/deploy-and-verify.mden/docs/api-gateway/next/setup/artifact-templating.mden/docs/api-gateway/next/setup/health-checks.mden/docs/llms.txten/mkdocs.yml
|
|
||
| ```bash | ||
| curl http://localhost:9094/api/admin/v0.9/health | ||
| curl http://localhost:9094/api/admin/v1/health |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Make the verification command fail on HTTP errors.
Without --fail, curl exits successfully for HTTP 4xx and 5xx responses. This step can appear successful when /api/admin/v1/health returns an error. Add --fail.
Proposed command
-curl http://localhost:9094/api/admin/v1/health
+curl --fail --silent --show-error http://localhost:9094/api/admin/v1/health📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| curl http://localhost:9094/api/admin/v1/health | |
| curl --fail --silent --show-error http://localhost:9094/api/admin/v1/health |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In
`@en/docs/api-gateway/next/deployment/deployment-modes/kubernetes/kubernetes-standalone.md`
at line 246, Update the Kubernetes standalone verification curl command for
/api/admin/v1/health to include the --fail option, ensuring HTTP 4xx and 5xx
responses cause the command to exit unsuccessfully.
| @@ -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." | |||
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Correct the duplicated health-page descriptions. Both values exceed 158 characters and incorrectly assign /_gateway-health to every component.
en/docs/api-gateway/next/setup/health-checks.md#L3-L3: use a shorter description that names the Gateway Controller, Router, Policy Engine, Docker Compose, and Kubernetes without listing a shared endpoint.en/docs/api-gateway/1.2.0/setup/health-checks.md#L3-L3: apply the same corrected description.
As per path instructions, every Markdown page under en/docs/ must include a description under 158 characters.
📍 Affects 2 files
en/docs/api-gateway/next/setup/health-checks.md#L3-L3(this comment)en/docs/api-gateway/1.2.0/setup/health-checks.md#L3-L3
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@en/docs/api-gateway/next/setup/health-checks.md` at line 3, Shorten the
description at en/docs/api-gateway/next/setup/health-checks.md:3 and
en/docs/api-gateway/1.2.0/setup/health-checks.md:3 to the same text under 158
characters, naming the Gateway Controller, Router, Policy Engine, Docker
Compose, and Kubernetes without assigning a shared /_gateway-health endpoint to
every component.
Source: Path instructions
| | 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 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
Define HTTPS before using it. Both pages use the abbreviation in the port table before expanding it later.
en/docs/api-gateway/next/setup/health-checks.md#L59-L68: expandHypertext Transfer Protocol Secure (HTTPS)in the port table, then useHTTPSin the following sentence.en/docs/api-gateway/1.2.0/setup/health-checks.md#L59-L68: apply the same acronym ordering.
As per path instructions, define every acronym and initialism at first use.
📍 Affects 2 files
en/docs/api-gateway/next/setup/health-checks.md#L59-L68(this comment)en/docs/api-gateway/1.2.0/setup/health-checks.md#L59-L68
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@en/docs/api-gateway/next/setup/health-checks.md` around lines 59 - 68, Define
“Hypertext Transfer Protocol Secure (HTTPS)” in the Ports table before the
acronym appears elsewhere, then use HTTPS in the explanatory sentence. Apply
this same acronym-ordering change in
en/docs/api-gateway/next/setup/health-checks.md lines 59-68 and
en/docs/api-gateway/1.2.0/setup/health-checks.md lines 59-68.
Source: Path instructions
2 participants
Purpose
The API Platform Gateway setup docs had no page explaining how to configure liveness and readiness checks for the Gateway Controller, Router, and Policy Engine, so operators wiring Docker Compose or Kubernetes probes had no reference for the available health endpoints. This PR adds that page and pins
setuptoolsin the docs build environment to keep the site build stable.Resolves:
Checklist
llms.txt(located aten/docs/llms.txt) is updated for AI readiness content.Goals
/api/admin/v1/health), the Router (/_gateway-health/healthyand/_gateway-health/ready), and the Policy Engine (/health).healthcheckblocks and KubernetesreadinessProbe/livenessProbeconfiguration.setuptoolsto a version below 81.Approach
en/docs/api-gateway/next/setup/health-checks.md, covering the three health surfaces, their default ports, examplecurlcommands, and tabbed Docker Compose and Kubernetes configuration snippets.en/mkdocs.ymland added prev/next navigation links onartifact-templating.md.setuptools<81inen/requirements.txt.User stories
As a platform operator deploying the API Platform Gateway, I want documented health-check endpoints and probe configuration examples so I can configure Docker Compose and Kubernetes to detect and restart unhealthy gateway components.
Release note
Added documentation for configuring liveness and readiness health checks for the Gateway Controller, Router, and Policy Engine.
Documentation
This PR is entirely a documentation change: en/docs/api-gateway/next/setup/health-checks.md.
Training
N/A — no training content covers gateway health checks yet.
Certification
N/A — documentation-only addition, no product behavior change to certify.
Marketing
N/A
Automation tests
Unit tests
N/A — documentation-only change.
Integration tests
Verified locally that
mkdocs buildsucceeds and the new page renders with working navigation links.Security checks
Samples
N/A
Related PRs
None
Migrations (if applicable)
N/A
Test environment
Built and previewed with
mkdocs serveon Linux.Learning
Reviewed the Gateway Controller, Router, and Policy Engine source configuration for their admin/health ports and endpoint paths to document accurate defaults and auth-exemption behavior.