Eclipse MicroProfile Health Check API
Since Payara Server 4.1.2.181 and 5.181
Provided version of the API: MicroProfile Health Check 3.1
Background
The Health Check API was created to allow easier probing of the state of computing nodes with a cloud infrastructure environment.
A full overview for the reasoning behind the API can be found in the README for the source code repository.
The complete specification is maintained in the same repository.
REST Endpoints
The MicroProfile Healthchecks API defines the following list of REST endpoints that are available from the root context at /health/${type} by default:
| Context | Type | Description |
|---|---|---|
|
Liveness |
On invocation, all registered health checks annotated with |
|
Readiness |
On invocation, all registered health checks annotated with |
'/health/started' |
Startup |
On invocation, all registered health checks annotated with '@Startup' are performed and the results aggregated. |
|
Readiness + Liveness + Startup |
On invocation, all registered health checks annotated with |
This root endpoint can be altered using the set-microprofile-healthcheck-configuration asadmin command to prevent collisions with other HTTP endpoints that might need to use the health context root.
| This endpoint will not be available until at least one application has been deployed. |
Health Check Configuration
Health Check can be configured by using Admin Console or Asadmin commands.
Since 5.183
Using the Admin Console
To configure the Health Check in the Admin Console, go to Configuration → [instance-configuration (like server-config)] → MicroProfile → Health Check:
Using Asadmin Commands
The following administration commands can be used to configure the MicroProfile Healthcheck service:
set-microprofile-healthcheck-configuration
Since Payara Server 4.1.2.182 and 5.182
- Usage
asadmin set-microprofile-healthcheck-configuration
[--enabled=true|false]
[--securityenabled=true|false]
[--roles=<role-list>]
[--endpoint=<context-root[default:health]>]
[--target=<target[default:server]>]
[--virtualservers=<virtualserver-list>]
- Aim
-
Enables or disables the MicroProfile healthcheck service and configures the endpoint where all registered health checks are exposed.
Command Options
| Option | Type | Description | Default | Mandatory |
|---|---|---|---|---|
|
Boolean |
Enables or disables the service |
true |
No |
|
Boolean |
Whether or not secure access to the health-check endpoint is enabled. Since Payara Server 5.193 |
false |
No |
|
String |
If defined, the endpoint will be assigned to a list of the role specified as a comma-separated. Since Payara Server 5.193 |
|
No |
|
String |
The context root used to expose the health checks endpoint. |
health |
No |
|
String |
The target configuration where the command should be run |
server |
No |
|
String |
If defined, the '/health' endpoint will be assigned to the list of virtual servers specified as a comma-separated list of names. Otherwise, the endpoint will be assigned to all virtual servers available. Since Payara Server 4.1.2.184 and 5.184 |
- |
No |
| Changes made with this command will only be applied when the server or instance is restarted. |
Security Configuration
By default, HealthCheck endpoints bind to root context application which is
default-web-module (docroot) system application and default-web-module
application uses the default realm (file) of the server. If user application deployed
with the empty context-root then the security configuration of the deployed
application will be shared by HealthCheck endpoints.
Upgrading from MicroProfile 3.x to 4.x
MicroProfile 4.0 brings with it a number of changes to MicroProfile Health. The main incompatible change
brought in by this upgrade is the removal of the deprecated @Health annotation.
There isn’t a workaround for this, the annotation is simply gone: all health checks must be registered as a
@Readiness, @Liveness, or @Startup check.