16.1.1.15. Healthcheck endpoints¶

The healthcheck REST API exposes liveness, readiness and resolver connectivity probes intended for orchestrators (Kubernetes, Docker health checks, monitoring systems).

Endpoints:

GET /healthz/ : Combined health check for liveness and readiness.
GET /healthz/startupz : Startup check to confirm if the app has started.
GET /healthz/livez : Liveness check to verify if the app is running.
GET /healthz/readyz : Readiness check to confirm if the app is ready to serve requests.
GET /healthz/resolversz : Resolver check that tests the connection to all LDAP and SQL resolvers.

The endpoints are anonymous so that orchestrators can probe them without credentials. /healthz/resolversz returns the overall resolver-connectivity status to anyone, but reveals the individual resolver names only to an authenticated administrator. Because the /healthz endpoints expose information about this server without authentication, they should be reachable only from a trusted network and not exposed to untrusted clients.

For information on the current standard and how to configure these probes, see the Kubernetes documentations:

https://kubernetes.io/docs/reference/using-api/health-checks/

https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/

GET /healthz/¶

Combined health check endpoint for liveness and readiness.

The health check verifies the liveness of the app, ensuring it is running, and the readiness, ensuring the app and its dependencies are ready to serve requests.

resheader Content-Type:

application/json

status 200:

Application is live and ready.

status 503:

Application is live but not ready.

Example Request:

GET /healthz HTTP/1.1
Host: example.com
Accept: application/json

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "ready",
    "hsm": "OK"
}

GET /healthz/startupz¶

Startup check endpoint that indicates if the app has started.

This endpoint returns a status of “started” if the app is initialized and running, otherwise it returns “not started” with an HTTP status code of 503.

resheader Content-Type:

application/json

status 200:

Application has started.

status 503:

Application has not started yet.

Example Request:

GET /healthz/startupz HTTP/1.1
Host: example.com
Accept: application/json

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "started"
}

GET /healthz/livez¶

Liveness check endpoint that indicates if the app is running.

This endpoint returns an HTTP status 200 and a JSON object indicating that the application is live and running.

resheader Content-Type:

application/json

status 200:

Application is live.

Example Request:

GET /healthz/livez HTTP/1.1
Host: example.com
Accept: application/json

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "OK"
}

GET /healthz/readyz¶

Readiness check endpoint that indicates if the app is ready to serve requests.

The endpoint checks the readiness of the app, ensuring that the app has started and the HSM (Hardware Security Module) is in a ready state. If any condition is not met, a 503 status is returned with appropriate information.

resheader Content-Type:

application/json

status 200:

Application is ready.

status 503:

Application is not ready or HSM is not ready.

Example Request:

GET /healthz/readyz HTTP/1.1
Host: example.com
Accept: application/json

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "ready",
    "hsm": "OK"
}

GET /healthz/resolversz¶

Test connectivity to every configured LDAP and SQL resolver.

The endpoint tries to open a connection to each resolver, returning OK for resolvers that respond and fail for those that don’t. The top-level status field is OK if every resolver responded, fail if any resolver failed, or error if an unexpected exception aborted the probe.

The endpoint is anonymous so that orchestrators (Kubernetes, Docker, monitoring) can poll it without credentials: an unauthenticated caller receives the overall status only. The individual resolver names are returned solely to an authenticated administrator, so they are never disclosed to anonymous callers. If the require_auth_for_resolver_details policy (scope authz) is set, a present but invalid or non-admin token is rejected with 401 instead of being treated as anonymous; a request without an Authorization header is still served the status. The probe result is cached for PI_HEALTHZ_RESOLVER_CACHE_SECONDS seconds (default 10; set to 0 to disable), so frequent or repeated calls do not re-open a connection to every backend each time.

Note

The /healthz endpoints expose information about this server without authentication, so they should be reachable only from a trusted network (the orchestrator / monitoring network) and not exposed to untrusted clients. A dedicated operational guide for deploying and securing these probes is planned.

Response Headers:

Content-Type – application/json

Status Codes:

200 OK – probe completed; result in the body — the per-resolver names are included only for an authenticated administrator.
401 Unauthorized – the require_auth_for_resolver_details policy is set and the request carried a present but invalid or non-admin token.
503 Service Unavailable – an unexpected exception aborted the probe.

Example Request:

GET /healthz/resolversz HTTP/1.1
Host: example.com
Accept: application/json

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "OK",
  "ldapresolver": {
    "ldapresolver1": "OK",
    "ldapresolver2": "OK"
  },
  "sqlresolver": {
    "sqlresolver1": "OK",
    "sqlresolver2": "OK"
  }
}