[[MicroProfile_Health_SmallRye]]
= MicroProfile Health Subsystem Configuration

Support for https://microprofile.io/project/eclipse/microprofile-health[Eclipse MicroProfile Health] is provided by
 the _microprofile-health-smallrye_ subsystem.

[[required-extension-microprofile-health-smallrye]]
== Required Extension

This extension is included in the standalone configurations included in the
WildFly distribution.

You can also add the extension to a configuration without it either by adding
an `<extension module="org.wildfly.extension.microprofile.health-smallrye"/>`
element to the xml or by using the following CLI operation:

[source,options="nowrap"]
----
[standalone@localhost:9990 /]/extension=org.wildfly.extension.microprofile.health-smallrye:add
----

== Management Operation

The healthiness of the application server can be queried by calling the `check`:

[source,options="nowrap"]
----
[standalone@localhost:9990 /] /subsystem=microprofile-health-smallrye:check
{
    "outcome" => "success", <1>
    "result" => {
        "outcome" => "UP", <2>
        "checks" => []
    }
}
----
<1> this `outcome` means that the management operation is successful
<2> this `outcome` corresponds to the health check, `UP` if the application server is healthy, `DOWN` else.

== HTTP Endpoints

The MicroProfile Health Check specifications defines three HTTP endpoints:
* `/health` to test both the liveness and readiness of the runtime.
* `/health/live` to test the liveness of the runtime.
* `/health/ready` to test the readiness of the runtime.

The Health HTTP endpoints are accessible on WildFly HTTP management interface (e.g. http://localhost:9990/health[http://localhost:9990/health]).

=== Secured Access to the HTTP endpoints

Secured access to the HTTP endpoint is controlled by the `security-enabled` attribute of the `/subsystem=microprofile-health-smallrye` resource.
If it is set to `true`, the HTTP client must be authenticated.

If the application server is healthy, it will return a `200 OK` response:

[source,shell]
----
$ curl -v http://localhost:9990/health
< HTTP/1.1 200 OK
...
{"outcome":"UP","checks":[]}
----

If the application server (and its deployment) is not healthy, it returns `503 Service Unavailable`

[source,shell]
----
$ curl -v http://localhost:9990/health
< HTTP/1.1 503 Service Unavailable
...
{"outcome":"DOWN","checks":[{"name":"myFailingProbe","state":"DOWN","data":{"foo":"bar"}}]}
----

If security has been enabled, the HTTP client must pass the credentials corresponding to a management user
created by the `add-user` script. For example:

[source,shell]
----
$ curl -v --digest -u myadminuser:myadminpassword http://localhost:9990/health
< HTTP/1.1 200 OK
...
{"outcome":"UP","checks":[]}
----

If the authentication fails, the  server will reply with a `401 NOT AUTHORIZED` response.

=== Global Status when probes are not defined

By default, the HTTP endpoints will return `UP` if there are no health check probes defined by the application.

However, it is possible to change this behaviour.
The `/health/live` HTTP endpoint (as well as the `check-live` management operation) can return `DOWN` when there are no liveness check probes by setting the `empty-liveness-checks-status` attribute
on the `subsystem` resource to `DOWN`.
Similarly, the `/health/ready` HTTP endpoint (as well as the `check-ready` management operation) can return `DOWN` when there are no readiness check probes by setting the `empty-readiness-checks-status` attribute
on the `subsystem` resource to `DOWN`.

This allows application to ensure that the HTTP liveness and readiness endpoints will return `DOWN` until their probes are deployed and used to determine the actual
liveness and readiness state of the application.

[NOTE]
There is a specific behaviour for deployments that provides no _readiness_ probes. In that the case, WildFly automatically adds a readiness probe for the deployment that always return
`UP`. This allows existing deployments that do not provide readiness probes to configure WildFly so it will not be ready until this deployment is actually deployed.


== Component Reference

The Eclipse MicroProfile Health is implemented by the SmallRye Health project.

****

* https://microprofile.io/project/eclipse/microprofile-health[Eclipse MicroProfile Health]
* http://github.com/smallrye/smallrye-health/[SmallRye Health]

****