Management Endpoints
nevisMeta provides a liveness endpoint and a readiness endpoint on a dedicated management port. Use them to detect the current state of an instance, for example to configure container probes in Kubernetes.
To configure the probes in Kubernetes, see the Kubernetes documentation on liveness, readiness, and startup probes. Use the paths and the api-version header described on this page.
The management endpoints are disabled by default. To enable them, set management.healthchecks.enabled to true. See Configuration.
Endpoints
The endpoints are served over plain HTTP on the management port and support only the GET method. The default management port is 9005.
| Endpoint | Purpose | Default URL |
|---|---|---|
/liveness | Reports whether the instance is running. | http://hostname:9005/liveness |
/readiness | Reports whether the instance is ready to handle requests. | http://hostname:9005/readiness |
API Versioning
The response format of /liveness and /readiness depends on the api-version request header.
| Header value | Response |
|---|---|
2.0 | JSON response (status and checks) compatible with the wire format and JSON payload of MicroProfile Health 4.0. |
1.0 | Legacy response. For /readiness, it is identical to the response of the legacy endpoint. |
| Missing, empty, or unsupported | The configured default version. |
The default version is 2.0. You can change it with management.healthchecks.default-api-version. See Configuration.
Responses contain the following headers:
| Header | Description |
|---|---|
api-version | The API version that was used for the response. |
Vary | Always api-version. |
Cache-Control | Always no-store. |
Liveness
The liveness endpoint reports whether the instance is up and running. The instance can be running but not ready to handle requests, for example because of a misconfiguration. Use readiness to detect that. The liveness endpoint does not access the database.
| Aspect | Value |
|---|---|
| URL | http://hostname:9005/liveness |
| Method | GET |
Response, api-version 2.0 | JSON object with status UP and an empty checks list. See the example. |
Response, api-version 1.0 | JSON object with status UP. See the example. |
| HTTP status code | 200 (OK) |
| HTTP status code on processing failure | 500 (Internal Server Error) |
Readiness
The readiness endpoint reports whether the instance is ready to handle requests. nevisMeta is ready if it can reach its database. If the check fails, orchestrators such as Kubernetes stop routing traffic to the instance.
| Aspect | Value |
|---|---|
| URL | http://hostname:9005/readiness |
| Method | GET |
Response, api-version 2.0 | JSON object with status and a database check in checks. See the examples. |
Response, api-version 1.0 | JSON object with the readiness result. See the examples. |
| HTTP status code if ready | 200 (OK) |
HTTP status code if not ready, api-version 2.0 | 503 (Service Unavailable) |
HTTP status code if not ready, api-version 1.0 | 200 (OK). The response body shows that the instance is not ready. Probes that only check the HTTP status code do not detect it. |
| HTTP status code on processing failure | 500 (Internal Server Error) |
The readiness result is the combination of the following checks:
| Check | Available | Description |
|---|---|---|
database | Always | The SQL database is reachable. See Database Check. |
Database Check
The database check uses two methods. During normal operation with business traffic, the result is mainly based on the outcome of the connection pool borrows of the real traffic (passive check). If there is no or little business traffic, for example at startup, the check borrows and validates a connection itself (active check). You can tune it with the management.healthchecks.database.* properties. See Configuration.
With api-version 2.0, the details of the check are returned in data. With api-version 1.0, they are not part of the response.
The active check can delay the response by up to management.healthchecks.database.active.timeout, so set the probe timeout higher than this value.
Legacy Endpoints (Deprecated)
The legacy endpoint is deprecated and is removed in November 2027. Use /liveness and /readiness instead.
| Endpoint | Default URL |
|---|---|
/health | http://hostname:9005/health |
The legacy endpoint always returns the 1.0 readiness response with the HTTP status code 200 and ignores the api-version request header. Responses contain the Deprecation and Sunset headers.
Configuration
Configure the management endpoints in nevismeta.properties. Changes to the properties take effect after a restart. See also Management server configuration.
| Property | Description |
|---|---|
management.Mandatory: No Default: localhost | Host the management server binds to. To reach the endpoints from outside the host, for example with Kubernetes probes, set it to 0.0.0.0. |
management.Mandatory: No Default: 9005 | Management port. |
management.Mandatory: Yes, to use the endpoints Default: false | Enables the management endpoints. |
management.Mandatory: No Default: 2.0 | API version used if the api-version request header is missing, empty, or unsupported. Allowed values: 1.0, 2.0. An invalid value is ignored with a warning. |
management.Mandatory: No Default: 2s | Time limit of the active database check. Allowed range: 1ms to 60s. |
management.Mandatory: No Default: 10s | How long the outcome of a connection pool borrow counts as evidence. |
management.Mandatory: No Default: 3 | Number of consecutive failed borrows that make the readiness DOWN. Allowed range: 1 to 256. |
management.Mandatory: No Default: 5s | Wait time for a pool connection from which the pool counts as exhausted. |
Example:
management.server.host=0.0.0.0
management.server.port=9005
management.healthchecks.enabled=true
management.healthchecks.default-api-version=2.0
management.healthchecks.database.active.timeout=2s
management.healthchecks.database.passive.evidence-max-age=10s
management.healthchecks.database.passive.failure-threshold=3
management.healthchecks.database.passive.pool-wait-threshold=5s
Response Examples
Liveness
API version 2.0
Alive (HTTP status code 200):
{
"status": "UP",
"checks": []
}
API version 1.0
Alive (HTTP status code 200):
{
"status": "UP"
}
Readiness
API version 2.0
Ready (HTTP status code 200):
{
"status": "UP",
"checks": [
{
"name": "database",
"status": "UP",
"data": {
"reason": "ACTIVE_CHECK_OK",
"source": "active",
"poolActive": 0,
"poolIdle": 10,
"poolTotal": 10,
"poolMax": 10,
"threadsAwaiting": 0,
"consecutiveFailures": 0,
"lastSuccessAgeMs": 516625,
"lastBorrowWaitMs": 0,
"activeCheck": "OK",
"activeCheckDurationMs": 1
}
}
]
}
Not ready (HTTP status code 503):
{
"status": "DOWN",
"checks": [
{
"name": "database",
"status": "DOWN",
"data": {
"reason": "ACTIVE_CHECK_TIMEOUT",
"source": "active",
"poolActive": 0,
"poolIdle": 8,
"poolTotal": 8,
"poolMax": 10,
"threadsAwaiting": 0,
"activeCheckAwaitingConnection": true,
"consecutiveFailures": 0,
"lastSuccessAgeMs": 631251,
"lastBorrowWaitMs": 0,
"activeCheck": "TIMED_OUT",
"activeCheckDurationMs": 2002
}
}
]
}
API version 1.0
Ready (HTTP status code 200):
{
"status": "UP"
}
Not ready (HTTP status code 200):
{
"health is": "DOWN"
}