docs: replace GET /health references with /livez and /admin/v1/health across configuration, reference, and operations docs

[janiussyafiq]

Summary

Several customer-facing docs still reference GET /health on the public proxy and admin listeners, but PR #257 (issue #253) renamed that unauthenticated liveness route to /livez on both listeners. The documented curl commands return HTTP 404 against the current main (cd2acc99); the canonical public surface is now:

• /livez — unauthenticated liveness, served on both the proxy listener (port 3000) and the admin listener (port 3001), returns 200 OK with a plain-text body.
• GET /admin/v1/health — authenticated per-model operator health, served on the admin listener only, requires Authorization: Bearer <admin_key>.

These stale references were introduced by PR #249 (the docs rebuild) and were not updated when PR #257 landed the rename.

Affected documents

File	Line	Current text	Should read
docs/configuration/admin-api.md	31	- GET /health (entry in public-routes list)	- GET /livez
docs/configuration/admin-api.md	54	- GET /health (entry under "Current Admin Surface")	- GET /livez
docs/configuration/admin-api.md	100	Public routes such as /health, /metrics, and the OpenAPI endpoints do not require admin auth.	Public routes such as /livez, /metrics, and the OpenAPI endpoints do not require admin auth.
docs/configuration/admin-api.md	102	Use GET /health for simple admin-listener reachability. Use GET /admin/v1/health when you need authenticated per-model operator health.	Use GET /livez for simple admin-listener reachability. Use GET /admin/v1/health when you need authenticated per-model operator health.
docs/configuration/bootstrap-config.md	210	curl -s http://127.0.0.1:3000/health	curl -s http://127.0.0.1:3000/livez
docs/configuration/bootstrap-config.md	216	curl -s http://127.0.0.1:3001/health	curl -s http://127.0.0.1:3001/livez
docs/reference/admin-api-reference.md	9	- GET /health	- GET /livez
docs/operations/production-deployment.md	88	1. GET /health returns 200	1. GET /livez returns 200
docs/operations/production-deployment.md	89	2. admin-listener GET /health returns 200 in standalone mode	2. admin-listener GET /livez returns 200 in standalone mode
docs/operations/network-and-security.md	23	Current admin design intentionally leaves /health, /metrics, and OpenAPI endpoints unauthenticated on that private listener, so network placement matters.	Current admin design intentionally leaves /livez, /metrics, and OpenAPI endpoints unauthenticated on that private listener, so network placement matters.
docs/operations/upgrades-and-compatibility.md	21	1. GET /health	1. GET /livez
docs/operations/upgrades-and-compatibility.md	22	2. admin-listener GET /health	2. admin-listener GET /livez
docs/operations/troubleshooting.md	94	1. check GET /health	1. check GET /livez
docs/operations/troubleshooting.md	95	2. check admin-listener GET /health, then GET /admin/v1/health in standalone mode	2. check admin-listener GET /livez, then GET /admin/v1/health in standalone mode

/admin/v1/health references elsewhere in these files are correct and require no change.

Steps to reproduce

Run the documented commands against the current main (cd2acc99):

# Documented (stale) — both return 404
curl -is http://127.0.0.1:3000/health
curl -is http://127.0.0.1:3001/health

# Actual routes — both return 200 OK
curl -is http://127.0.0.1:3000/livez
curl -is http://127.0.0.1:3001/livez

# Authenticated operator health on admin listener
curl -is -H "Authorization: Bearer <admin_key>" \
     http://127.0.0.1:3001/admin/v1/health

The first two commands match the snippets in docs/configuration/bootstrap-config.md verbatim and reproduce the 404. The remaining commands match the current code surface.

Source Reference

• crates/aisix-admin/src/lib.rs:61 — .route("/livez", get(livez)) (the unauthenticated liveness route, shared by both listeners)
• crates/aisix-admin/src/lib.rs:140 — .route("/admin/v1/health", get(...)) (the authenticated operator-facing health endpoint)
• PR fix(health): rename public liveness route to /livez #257 — fix(health): rename public liveness route to /livez (the rename itself)
• Issue Rename hardened /health endpoint to /livez #253 — Rename hardened /health endpoint to /livez (the original decision)

Proposed Resolution

Update each line in the table above to use the correct route. The change is a mechanical text replacement in every case (no behavioral or semantic rewrite is required); /admin/v1/health references are already correct and must remain unchanged.

Single docs PR updating all listed files as a unit, since the fix is mechanically identical across them (post-#257 cleanup). Title proposal:

docs: post-#257 — replace stale GET /health references with /livez and /admin/v1/health

This matches the multi-file docs PR shape used in #281 and #249.

References

• Issue Rename hardened /health endpoint to /livez #253 — Rename hardened /health endpoint to /livez
• PR fix(health): rename public liveness route to /livez #257 — fix(health): rename public liveness route to /livez (branch fix/issue-253-rename-health-to-livez)
• PR docs: rebuild customer-facing docs across overview, config, cloud, ops, reference, and tutorials #249 — docs: rebuild customer-facing docs across overview, config, cloud, ops, reference, and tutorials (the version that introduced the stale text alongside the docs rebuild)
• Issue Harden unauthenticated /health to return only minimal status #252 — Harden unauthenticated /health to return only minimal status (the predecessor that hardened the response before Rename hardened /health endpoint to /livez #253 renamed the path)

[coderabbitai]

🔗 Related PRs

api7/api7-ee-3-gateway#1156 - fix: continuous healthcheck errors during ai-proxy-multi plugin configuration updates [merged]
api7/api7ee-3-control-plane#2307 - fix: include console status in healthz api [merged]
api7/api7ee-3-control-plane#2583 - fix: change file server API prefix from /api7 to /api [merged]
api7/api7ee-3-control-plane#2632 - fix: rename health check schema field request_body to http_req_body [merged]
#278 - fix(server): derive etcd endpoint on subsequent boot from cp_base_url [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!