Skip to main content
Version: 9.2605.x RR

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.

Kubernetes probes

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.

EndpointPurposeDefault URL
/livenessReports whether the instance is running.http://hostname:9005/liveness
/readinessReports 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 valueResponse
2.0JSON response (status and checks) compatible with the wire format and JSON payload of MicroProfile Health 4.0.
1.0Legacy response. For /readiness, it is identical to the response of the legacy endpoint.
Missing, empty, or unsupportedThe 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:

HeaderDescription
api-versionThe API version that was used for the response.
VaryAlways api-version.
Cache-ControlAlways 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.

AspectValue
URLhttp://hostname:9005/liveness
MethodGET
Response, api-version 2.0JSON object with status UP and an empty checks list. See the example.
Response, api-version 1.0JSON object with status UP. See the example.
HTTP status code200 (OK)
HTTP status code on processing failure500 (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.

AspectValue
URLhttp://hostname:9005/readiness
MethodGET
Response, api-version 2.0JSON object with status and a database check in checks. See the examples.
Response, api-version 1.0JSON object with the readiness result. See the examples.
HTTP status code if ready200 (OK)
HTTP status code if not ready, api-version 2.0503 (Service Unavailable)
HTTP status code if not ready, api-version 1.0200 (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 failure500 (Internal Server Error)

The readiness result is the combination of the following checks:

CheckAvailableDescription
databaseAlwaysThe 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)​

Deprecated

The legacy endpoint is deprecated and is removed in November 2027. Use /liveness and /readiness instead.

EndpointDefault URL
/healthhttp://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.

PropertyDescription
management.server.host
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.server.port
Mandatory: No
Default: 9005
Management port.
management.healthchecks.enabled
Mandatory: Yes, to use the endpoints
Default: false
Enables the management endpoints.
management.healthchecks.default-api-version
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.healthchecks.database.active.timeout
Mandatory: No
Default: 2s
Time limit of the active database check. Allowed range: 1ms to 60s.
management.healthchecks.database.passive.evidence-max-age
Mandatory: No
Default: 10s
How long the outcome of a connection pool borrow counts as evidence.
management.healthchecks.database.passive.failure-threshold
Mandatory: No
Default: 3
Number of consecutive failed borrows that make the readiness DOWN. Allowed range: 1 to 256.
management.healthchecks.database.passive.pool-wait-threshold
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"
}