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
📝 WalkthroughWalkthroughAdded an API Gateway health checks guide. It documents health endpoints, probe configurations, access behavior, and test commands. Navigation includes the guide, and existing examples use ChangesHealth checks documentation
Estimated code review effort: 2 (Simple) | ~10 minutes 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
| 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 en/docs/ uses active present-tense voice.
Also applies to: 70-70
🤖 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 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.
Source: Path instructions
| 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 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 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.
Source: Path instructions
1 participant
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.