This is an automated email from the ASF dual-hosted git repository.
mchades pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/gravitino.git
The following commit(s) were added to refs/heads/main by this push:
new aad5763c13 [#10856] docs: Add health check endpoint documentation
(#11261)
aad5763c13 is described below
commit aad5763c137cd6c188ad43a20b3f178b48559b82
Author: Jerry Shao <[email protected]>
AuthorDate: Thu May 28 11:17:58 2026 +0800
[#10856] docs: Add health check endpoint documentation (#11261)
### What changes were proposed in this pull request?
Add user-facing documentation for the health check REST endpoints
introduced in #10840, #10847, and #11102.
- **`docs/gravitino-server-config.md`**: New `### Health check
endpoints` section (after Metrics configuration) covering `GET
/api/health/live`, `GET /api/health/ready`, `GET /api/health`, the
root-level GTM aliases (`/health`, `/health/live`, `/health/ready`,
`/health.html`), the
`gravitino.server.health.entityStore.probeTimeoutMs` configuration
property, and UP/DOWN JSON response examples.
- **`docs/iceberg-rest-service.md`**: New `### Health check endpoints`
section (after Misc configurations) covering `GET /iceberg/health/live`,
`GET /iceberg/health/ready`, `GET /iceberg/health`, the same root-level
GTM aliases forwarding to `/iceberg/health*`, and UP/DOWN JSON response
examples.
### Why are the changes needed?
The health endpoints were implemented but lacked user-facing
documentation, making it difficult for operators deploying Gravitino in
containerized or enterprise environments to discover and configure the
probe endpoints.
Fix: #10856
### Does this PR introduce _any_ user-facing change?
No code changes. Documentation only.
### How was this patch tested?
Documentation change only; no test required.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Sonnet 4.6 <[email protected]>
---
docs/gravitino-server-config.md | 75 ++++++++++++++++++++++++++++++++++++-----
docs/iceberg-rest-service.md | 49 +++++++++++++++++++++++++++
2 files changed, 115 insertions(+), 9 deletions(-)
diff --git a/docs/gravitino-server-config.md b/docs/gravitino-server-config.md
index 1a2ac29f60..2aec2d9183 100644
--- a/docs/gravitino-server-config.md
+++ b/docs/gravitino-server-config.md
@@ -248,11 +248,11 @@ The audit log framework defines how audit logs are
formatted and written to vari
Gravitino provides a default implementation to log basic audit information to
a file. You can extend the audit system by implementing the corresponding
interfaces.
-| Property name | Description
| Default value | Required | Since Version
|
-|---------------------------------------|----------------------------------------|------------------------------------------------|----------|------------------|
-| `gravitino.audit.enabled` | The audit log enable flag.
| false | NO |
0.7.0-incubating |
-| `gravitino.audit.writer.className` | The class name of audit log writer.
| org.apache.gravitino.audit.FileAuditWriter | NO |
0.7.0-incubating |
-| `gravitino.audit.formatter.className` | The class name of audit log
formatter. | org.apache.gravitino.audit.v2.SimpleFormatterV2 | NO |
0.7.0-incubating |
+| Property name | Description
| Default value | Required | Since Version
|
+|---------------------------------------|----------------------------------------|-------------------------------------------------|----------|-------------------|
+| `gravitino.audit.enabled` | The audit log enable flag.
| false | NO |
0.7.0-incubating |
+| `gravitino.audit.writer.className` | The class name of audit log writer.
| org.apache.gravitino.audit.FileAuditWriter | NO |
0.7.0-incubating |
+| `gravitino.audit.formatter.className` | The class name of audit log
formatter. | org.apache.gravitino.audit.v2.SimpleFormatterV2 | NO |
0.7.0-incubating |
#### Audit log formatter
@@ -269,10 +269,10 @@ The `AuditLogWriter` interface enables writing audit logs
to different storage m
The following `gravitino.audit.writer.file.*` properties were accepted in
earlier versions but are now **deprecated** and have no effect.
`FileAuditWriter` emits a `WARN` log at startup if any of them are present.
Configure the equivalent behavior directly in `conf/log4j2.properties` instead.
| Deprecated property | Migration: configure in
`conf/log4j2.properties` |
-|-------------------------------------------------|--------------------------------------------------------------------|
-| `gravitino.audit.writer.file.fileName` |
`appender.audit_file.fileName` |
-| `gravitino.audit.writer.file.append` |
`appender.audit_file.append` |
-| `gravitino.audit.writer.file.flushIntervalSecs` | Use `immediateFlush` on
the appender or an async appender wrapper |
+|-------------------------------------------------|-------------------------------------------------------------------|
+| `gravitino.audit.writer.file.fileName` |
`appender.audit_file.fileName` |
+| `gravitino.audit.writer.file.append` |
`appender.audit_file.append` |
+| `gravitino.audit.writer.file.flushIntervalSecs` | Use `immediateFlush` on
the appender or an async appender wrapper |
Example — change the audit log path:
@@ -298,6 +298,63 @@ Refer to [security](security/security.md) for HTTPS and
authentication configura
|-------------------------------------------|------------------------------------------------------|---------------|----------|---------------|
| `gravitino.metrics.timeSlidingWindowSecs` | The seconds of Gravitino metrics
time sliding window | 60 | No | 0.5.1 |
+### Health check endpoints
+
+Gravitino exposes three health check endpoints following [MicroProfile
Health](https://microprofile.io/project/eclipse/microprofile-health) semantics.
All endpoints are exempt from authentication so that Kubernetes probes, load
balancers, and global traffic managers can reach them without credentials.
+
+| Endpoint | Description
| HTTP status |
+|-------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------|
+| `GET /api/health/live` | Liveness probe. Returns 200 as long as the HTTP
server thread can respond. Use this to determine whether to restart a pod.
| 200 |
+| `GET /api/health/ready` | Readiness probe. Returns 200 when the entity store
is reachable within the configured timeout; 503 when the entity store is
unavailable or slow. Use this to control traffic routing. | 200 / 503 |
+| `GET /api/health` | Aggregate check. Returns 200 when both liveness
and readiness pass; 503 when any check fails.
| 200 / 503 |
+
+Root-level aliases are also available for global traffic managers that require
probes at well-known root paths:
+
+| Alias | Forwards to |
+|---------------------|-------------------------|
+| `GET /health` | `GET /api/health` |
+| `GET /health/live` | `GET /api/health/live` |
+| `GET /health/ready` | `GET /api/health/ready` |
+| `GET /health.html` | `GET /api/health` |
+
+**Configuration:**
+
+| Property name | Description
| Default
value | Required | Since version |
+|------------------------------------------------------|-------------------------------------------------------------------------------------------|---------------|----------|---------------|
+| `gravitino.server.health.entityStore.probeTimeoutMs` | Timeout in
milliseconds for the entity-store readiness probe used by `/api/health/ready`.
| `2000` | No | 1.3.0 |
+
+**Response format:**
+
+All endpoints return a JSON body with the same shape. The `code` field is
always `0`. `status` is `UP` or `DOWN`. `checks` lists per-component results;
liveness reports `httpServer` and readiness reports `entityStore`.
+
+Healthy response (HTTP 200):
+
+```json
+{
+ "code": 0,
+ "status": "UP",
+ "checks": [
+ { "name": "httpServer", "status": "UP", "details": {} },
+ { "name": "entityStore", "status": "UP", "details": {} }
+ ]
+}
+```
+
+Unhealthy response (HTTP 503):
+
+```json
+{
+ "code": 0,
+ "status": "DOWN",
+ "checks": [
+ { "name": "httpServer", "status": "UP", "details": {} },
+ { "name": "entityStore", "status": "DOWN", "details": { "reason":
"timeout" } }
+ ]
+}
+```
+
+Possible `reason` values in the `entityStore` DOWN check: `timeout`,
`interrupted`, `probe-rejected`, or the class name of an unexpected exception.
+
### Memory settings
`GRAVITINO_MEM` sets JVM heap/metaspace flags for the Gravitino server and is
also read by the Iceberg REST server and Lance REST server launchers.
diff --git a/docs/iceberg-rest-service.md b/docs/iceberg-rest-service.md
index 03289cbee8..d623fba839 100644
--- a/docs/iceberg-rest-service.md
+++ b/docs/iceberg-rest-service.md
@@ -592,6 +592,55 @@ Gravitino provides the built-in
`org.apache.gravitino.iceberg.service.cache.Loca
|---------------------------------------------|--------------------------------------------------------------|---------------|----------|------------------|
| `gravitino.iceberg-rest.extension-packages` | Comma-separated list of
Iceberg REST API packages to expand. | (none) | No |
0.7.0-incubating |
+### Health check endpoints
+
+The Iceberg REST server exposes three health check endpoints following the
same [MicroProfile
Health](https://microprofile.io/project/eclipse/microprofile-health) semantics
as the main Gravitino server. All endpoints are exempt from authentication. The
readiness probe checks whether the `IcebergCatalogWrapperManager` has been
initialized — it performs no I/O and has no configurable timeout.
+
+| Endpoint | Description
|
HTTP status |
+|------------------------------|----------------------------------------------------------------------------------------------------------------------------|-------------|
+| `GET /iceberg/health/live` | Liveness probe. Returns 200 as long as the
HTTP server thread can respond.
| 200 |
+| `GET /iceberg/health/ready` | Readiness probe. Returns 200 when the catalog
wrapper manager is initialized; 503 when initialization is not yet complete. |
200 / 503 |
+| `GET /iceberg/health` | Aggregate check. Returns 200 when both
liveness and readiness pass; 503 when any check fails.
| 200 / 503 |
+
+Root-level aliases are also available for global traffic managers that require
probes at well-known root paths:
+
+| Alias | Forwards to |
+|---------------------|-----------------------------|
+| `GET /health` | `GET /iceberg/health` |
+| `GET /health/live` | `GET /iceberg/health/live` |
+| `GET /health/ready` | `GET /iceberg/health/ready` |
+| `GET /health.html` | `GET /iceberg/health` |
+
+**Response format:**
+
+All endpoints return a JSON body with the same shape as the main Gravitino
server. The `code` field is always `0`. `status` is `UP` or `DOWN`. Liveness
reports `httpServer` and readiness reports `catalogWrapperManager`.
+
+Healthy response (HTTP 200):
+
+```json
+{
+ "code": 0,
+ "status": "UP",
+ "checks": [
+ { "name": "httpServer", "status": "UP", "details": {} },
+ { "name": "catalogWrapperManager", "status": "UP", "details": {} }
+ ]
+}
+```
+
+Unhealthy response (HTTP 503):
+
+```json
+{
+ "code": 0,
+ "status": "DOWN",
+ "checks": [
+ { "name": "httpServer", "status": "UP", "details": {} },
+ { "name": "catalogWrapperManager", "status": "DOWN", "details": {
"reason": "catalog wrapper manager not initialized" } }
+ ]
+}
+```
+
### Memory settings
The Iceberg REST server uses `GRAVITINO_MEM` for JVM heap/metaspace flags.
Default: `-Xms1024m -Xmx1024m -XX:MaxMetaspaceSize=512m`. Launch scripts append
`GRAVITINO_MEM` to `JAVA_OPTS`; set it to adjust heap/metaspace sizes.
