Eclipse MicroProfile Health Check API

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 HealthCheck API defines the following list of REST endpoints that are available from the root context at /health/${type} by default:

Context Type Description

Context	Type	Description
`/health/live`	Liveness	On invocation, all registered health checks annotated with `@Liveness` are performed and the results aggregated.
`/health/ready`	Readiness	On invocation, all registered health checks annotated with `@Readiness` are performed and the results aggregated.
'/health/started'	Startup	On invocation, all registered health checks annotated with '@Startup' are performed and the results aggregated.
`/health`	Readiness + Liveness + Startup	On invocation, all registered health checks annotated with `@Liveness`, `@Readiness`, or `@Startup` are performed and the results aggregated.

/health/live

Liveness

On invocation, all registered health checks annotated with @Liveness are performed and the results aggregated.

/health/ready

Readiness

On invocation, all registered health checks annotated with @Readiness are performed and the results aggregated.

'/health/started'

Startup

On invocation, all registered health checks annotated with '@Startup' are performed and the results aggregated.

/health

Readiness + Liveness + Startup

On invocation, all registered health checks annotated with @Liveness, @Readiness, or @Startup are performed and the results aggregated.

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.

Using the Admin Console

To configure the Health Check in the Admin Console, go to Configuration → [instance-configuration (like server-config)] → MicroProfile → Health Check:

Set Health Check Configuration

Using Asadmin Commands

The following administration commands can be used to configure the MicroProfile Healthcheck service:

`set-microprofile-healthcheck-configuration`

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

Option	Type	Description	Default	Mandatory
`enabled`	Boolean	Enables or disables the service	true	No
`securityenabled`	Boolean	Whether or not secure access to the health-check endpoint is enabled.	false	No
`roles`	String	If defined, the endpoint will be assigned to a list of the role specified as a comma-separated.	`microprofile`	No
`endpoint`	String	The context root used to expose the health checks endpoint.	health	No
`target`	String	The target configuration where the command should be run	server	No
`virtualservers`	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.	-	No

enabled

Boolean

Enables or disables the service

true

securityenabled

Boolean

Whether or not secure access to the health-check endpoint is enabled.

false

roles

String

If defined, the endpoint will be assigned to a list of the role specified as a comma-separated.

microprofile

endpoint

String

The context root used to expose the health checks endpoint.

health

target

String

The target configuration where the command should be run

server

virtualservers

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.

Changes made with this command will only be applied when the server or instance is restarted.

Security Configuration

By default, HealthCheck endpoints bind to the root context application which is the default-web-module (also known as docroot) system application and the default-web-module application, which is secured under the default realm (file) of the server.

If a user application is deployed in the empty context-root, then the security configuration of this application will be shared by the HealthCheck endpoints, so exert extreme caution when making these changes.

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.