Skip to main content
Version: 9.2605.x RR

Management Endpoints

nevisFIDO 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 9089.

EndpointPurposeDefault URL
/livenessReports whether the instance is running.http://hostname:9089/liveness
/readinessReports whether the instance is ready to handle requests.http://hostname:9089/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, identical to the response of the legacy endpoints.
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.

AspectValue
URLhttp://hostname:9089/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)

Readiness​

The readiness endpoint reports whether the instance is ready to handle requests. If a check fails, orchestrators such as Kubernetes stop routing traffic to the instance.

AspectValue
URLhttp://hostname:9089/readiness
MethodGET
Response, api-version 2.0JSON object with status and one entry per check in checks. See the examples.
Response, api-version 1.0JSON object with status and one entry per check in components. See the examples.
HTTP status code if ready200 (OK)
HTTP status code if not ready503 (Service Unavailable)
HTTP status code on processing failure, api-version 2.0500 (Internal Server Error)
HTTP status code on processing failure, api-version 1.0503 (Service Unavailable)

The readiness result is the combination of the following checks:

CheckAvailableDescription
pingAlwaysThe application context handling FIDO protocol requests is running.
databaseWith a SQL session repositoryThe SQL database is reachable. See Database Check.
mds3FIDO2 with MDS3 configuredThe MDS3 metadata cache is initialized and not expired.
androidAttestationKeyRevocationFIDO UAFThe Android attestation CRL data is present and fresh.
fcmFIDO UAF with an FCM dispatcherFirebase Cloud Messaging is healthy.

With api-version 2.0 (MicroProfile Health 4.0), a check is either UP or DOWN, and any check that is not UP makes the readiness DOWN. With the legacy api-version 1.0, only DOWN results in HTTP status code 503.

By default, mds3, androidAttestationKeyRevocation, and fcm are excluded from the readiness result, because they depend on third-party services. You can change this with management.healthchecks.ignore-indicators. See Configuration.

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.

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 endpoints are deprecated and are removed in November 2027. Use /liveness and /readiness instead.

EndpointDefault URL
/nevisfido/livenesshttp://hostname:9089/nevisfido/liveness
/nevisfido/readinesshttp://hostname:9089/nevisfido/readiness
/nevisfido/healthhttp://hostname:9089/nevisfido/health

The legacy endpoints always return the 1.0 response and ignore the api-version request header. Responses contain the Deprecation and Sunset headers. The /nevisfido/health endpoint reports all checks and ignores management.healthchecks.ignore-indicators.

Configuration​

Configure the management endpoints in the management section of nevisfido.yml. Changes to the properties take effect after a restart.

PropertyDescription
management.server.port
Mandatory: No
Default: 9089
Management port. It must differ from server.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.ignore-indicators
Mandatory: No
Default:
  - mds3
  - androidAttestationKeyRevocation
  - fcm
Checks to exclude from the readiness result. Setting the property replaces the default list. Use an empty list to include all checks.
management.healthchecks.database.active.timeout
Mandatory: No
Default: 2s
Time limit of the active database check. Allowed range: 1ms to less than 5s.
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.
note

management.healthchecks.type is no longer supported. It is ignored with a warning and can be removed from the configuration.

Example:

management:
server:
port: 9089
healthchecks:
enabled: true
default-api-version: "2.0"
ignore-indicators:
- mds3
- androidAttestationKeyRevocation
- fcm
database:
active:
timeout: 2s
passive:
evidence-max-age: 10s
failure-threshold: 3
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": 57954,
"lastFailureAgeMs": 687956,
"lastFailureType": "SQLTransientConnectionException[sqlState=08000, errorCode=0]",
"lastBorrowWaitMs": 2,
"activeCheck": "OK",
"activeCheckDurationMs": 0
}
},
{
"name": "ping",
"status": "UP"
}
]
}

Not ready (HTTP status code 503):

{
"status": "DOWN",
"checks": [
{
"name": "database",
"status": "DOWN",
"data": {
"reason": "BORROW_FAILURES",
"source": "passive",
"poolActive": 0,
"poolIdle": 0,
"poolTotal": 0,
"poolMax": 10,
"threadsAwaiting": 0,
"consecutiveFailures": 4,
"lastSuccessAgeMs": 96395,
"lastFailureAgeMs": 6400,
"lastFailureType": "SQLTransientConnectionException[sqlState=08000, errorCode=0]",
"lastBorrowWaitMs": 30001,
"activeCheck": "NOT_RUN"
}
},
{
"name": "ping",
"status": "UP"
}
]
}

API version 1.0​

Ready (HTTP status code 200):

{
"status": "UP",
"components": {
"database": {
"details": {
"reason": "ACTIVE_CHECK_OK",
"source": "active",
"poolActive": 0,
"poolIdle": 10,
"poolTotal": 10,
"poolMax": 10,
"threadsAwaiting": 0,
"consecutiveFailures": 0,
"lastSuccessAgeMs": 57969,
"lastFailureAgeMs": 687971,
"lastFailureType": "SQLTransientConnectionException[sqlState=08000, errorCode=0]",
"lastBorrowWaitMs": 2,
"activeCheck": "OK",
"activeCheckDurationMs": 0
},
"status": "UP"
},
"ping": {
"status": "UP"
}
}
}

Not ready (HTTP status code 503):

{
"status": "DOWN",
"components": {
"database": {
"details": {
"reason": "BORROW_FAILURES",
"source": "passive",
"poolActive": 0,
"poolIdle": 0,
"poolTotal": 0,
"poolMax": 10,
"threadsAwaiting": 0,
"consecutiveFailures": 4,
"lastSuccessAgeMs": 96409,
"lastFailureAgeMs": 6414,
"lastFailureType": "SQLTransientConnectionException[sqlState=08000, errorCode=0]",
"lastBorrowWaitMs": 30001,
"activeCheck": "NOT_RUN"
},
"status": "DOWN"
},
"ping": {
"status": "UP"
}
}
}