The microprofile-health quickstart demonstrates the use of the MicroProfile Health specification in WildFly.

What is it?

MicroProfile Health allows applications to provide information about their state to external viewers which is typically useful in cloud environments where automated processes must be able to determine whether the application should be discarded or restarted.

Architecture

In this quickstart, we have a simple REST application that exposes MicroProfile Health functionalities at the /health/live, /health/ready, and /health/started endpoints according to the specification.

Browse the source

System Requirements

The application this project produces is designed to be run on WildFly Application Server 32 or later.

All you need to build this project is Java 11.0 (Java SDK 11) or later and Maven 3.6.0 or later. See Configure Maven to Build and Deploy the Quickstarts to make sure you are configured correctly for testing the quickstarts.

Use of the WILDFLY_HOME and QUICKSTART_HOME Variables

In the following instructions, replace WILDFLY_HOME with the actual path to your WildFly installation. The installation path is described in detail here: Use of WILDFLY_HOME and JBOSS_HOME Variables.

When you see the replaceable variable QUICKSTART_HOME, replace it with the path to the root directory of all of the quickstarts.

Start the WildFly Standalone Server

  1. Open a terminal and navigate to the root of the WildFly directory.

  2. Start the WildFly server with the MicroProfile profile by typing the following command.

    $ WILDFLY_HOME/bin/standalone.sh -c standalone-microprofile.xml
    Note
    		 For Windows, use the WILDFLY_HOME\bin\standalone.bat script.

Solution

We recommend that you follow the instructions that create the application step by step. However, you can also go right to the completed example which is available in this directory.

Build and Deploy the Quickstart

  1. Make sure WildFly server is started.

  2. Open a terminal and navigate to the root directory of this quickstart.

  3. Type the following command to build the quickstart.

    $ mvn clean package

  4. Type the following command to deploy the quickstart.

    $ mvn wildfly:deploy

This deploys the microprofile-health/target/microprofile-health.war to the running instance of the server.

You should see a message in the server log indicating that the archive deployed successfully.

Running the health check

The WildFly server directly exposes three REST endpoints:

  • /health/live - The application is up and running.

  • /health/ready - The application is ready to serve requests.

  • /health/started - The application is started allowing switch to liveness check.

  • /health - Accumulating all health check procedures in the application.

To check that the WildFly is working as expected:

All of the health REST endpoints return a simple JSON object with two fields:

  • status — the overall result of all the health check procedures

  • checks — an array of individual checks

The general status of the health check is computed as a logical AND of all the declared health check procedures.

Note
 Similarly, you can access http://localhost:9990/health/ready, http://localhost:9990/health/started, and http://localhost:9990/health

Congratulations! You successfully deployed and run this quickstart. If you wish to create the application step by step you can follow the subsequent sections.

Undeploy the Quickstart

When you are finished testing the quickstart, follow these steps to undeploy the archive.

  1. Make sure WildFly server is started.

  2. Open a terminal and navigate to the root directory of this quickstart.

  3. Type this command to undeploy the archive:

    $ mvn wildfly:undeploy

Run the Integration Tests

This quickstart includes integration tests, which are located under the src/test/ directory. The integration tests verify that the quickstart runs correctly when deployed on the server.

Follow these steps to run the integration tests.

  1. Make sure WildFly server is started.

  2. Make sure the quickstart is deployed.

  3. Type the following command to run the verify goal with the integration-testing profile activated.

    $ mvn verify -Pintegration-testing

Run the Quickstart in Red Hat CodeReady Studio or Eclipse

You can also start the server and deploy the quickstarts or run the Arquillian tests in Red Hat CodeReady Studio or from Eclipse using JBoss tools. For general information about how to import a quickstart, add a WildFly server, and build and deploy a quickstart, see Use Red Hat CodeReady Studio or Eclipse to Run the Quickstarts.

Creating the Maven Project

mvn archetype:generate \
    -DgroupId=org.wildfly.quickstarts \
    -DartifactId=microprofile-health \
    -DinteractiveMode=false \
    -DarchetypeGroupId=org.apache.maven.archetypes \
    -DarchetypeArtifactId=maven-archetype-quickstart
cd microprofile-health

Open the project in your favourite IDE.

Open the generated pom.xml.

The first thing to do is to change the packaging to war as this is required by the IDEs to recognize the application as a deployment:

<packaging>war</packaging>
Note
 For non-IDE deployments, the plain jar packaging is sufficient for the MicroProfile Health applications.

Next we need to setup our dependencies. Add the following section to your pom.xml:

<dependencyManagement>
  <dependencies>
    <!-- importing the microprofile BOM adds MicroProfile specs -->
    <dependency>
      <groupId>org.wildfly.bom</groupId>
      <artifactId>wildfly-microprofile</artifactId>
      <version>32.0.0.Final</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

Now we need to add the following two dependencies:

<!-- Import the MicroProfile Health API, we use provided scope as the API is included in the server -->
<dependency>
  <groupId>org.eclipse.microprofile.health</groupId>
  <artifactId>microprofile-health-api</artifactId>
  <scope>provided</scope>
</dependency>
<!-- Import the CDI API, we use provided scope as the API is included in the server -->
<dependency>
  <groupId>jakarta.enterprise</groupId>
  <artifactId>jakarta.enterprise.cdi-api</artifactId>
  <scope>provided</scope>
</dependency>
Note
 Because MicroProfile Health requires that all health checks are defined as CDI beans we need to also include the CDI API dependency.

Both dependencies can have provided scope. The versions are taken from the above defined BOM.

As we are going to be deploying this application to the WildFly server, let’s also add a maven plugin that will simplify the deployment operations (you can replace the generated build section):

<build>
  <!-- Set the name of the archive -->
  <finalName>${project.artifactId}</finalName>
  <plugins>
    <!-- Allows to use mvn wildfly:deploy -->
    <plugin>
      <groupId>org.wildfly.plugins</groupId>
      <artifactId>wildfly-maven-plugin</artifactId>
    </plugin>
  </plugins>
</build>

Setup the required Maven repositories (if you don’t have them set up in Maven global settings):

<repositories>
    <repository>
        <id>jboss-public-maven-repository</id>
        <name>JBoss Public Maven Repository</name>
        <url>https://repository.jboss.org/nexus/content/groups/public</url>
        <layout>default</layout>
        <releases>
            <enabled>true</enabled>
            <updatePolicy>never</updatePolicy>
        </releases>
        <snapshots>
            <enabled>true</enabled>
            <updatePolicy>never</updatePolicy>
        </snapshots>
    </repository>
    <repository>
        <id>redhat-ga-maven-repository</id>
        <name>Red Hat GA Maven Repository</name>
        <url>https://maven.repository.redhat.com/ga/</url>
        <layout>default</layout>
        <releases>
            <enabled>true</enabled>
            <updatePolicy>never</updatePolicy>
        </releases>
        <snapshots>
            <enabled>true</enabled>
            <updatePolicy>never</updatePolicy>
        </snapshots>
    </repository>
</repositories>
<pluginRepositories>
    <pluginRepository>
        <id>jboss-public-maven-repository</id>
        <name>JBoss Public Maven Repository</name>
        <url>https://repository.jboss.org/nexus/content/groups/public</url>
        <releases>
            <enabled>true</enabled>
        </releases>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </pluginRepository>
    <pluginRepository>
        <id>redhat-ga-maven-repository</id>
        <name>Red Hat GA Maven Repository</name>
        <url>https://maven.repository.redhat.com/ga/</url>
        <releases>
            <enabled>true</enabled>
        </releases>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </pluginRepository>
</pluginRepositories>

Now we are ready to start working with MicroProfile Health.

Creating your first health check

In this section, we create our first simple health check procedure.

Create the org.wildfly.quickstarts.microprofile.health.SimpleHealthCheck class:

package org.wildfly.quickstarts.microprofile.health;

import org.eclipse.microprofile.health.HealthCheck;
import org.eclipse.microprofile.health.HealthCheckResponse;
import org.eclipse.microprofile.health.Liveness;

import jakarta.enterprise.context.ApplicationScoped;

@Liveness
@ApplicationScoped
public class SimpleHealthCheck implements HealthCheck {

    @Override
    public HealthCheckResponse call() {
        return HealthCheckResponse.up("Simple health check");
    }
}

As you can see health check procedures are defined as implementations of the HealthCheck interface which are defined as CDI beans with the one of the following CDI qualifiers:

  • @Liveness - the liveness check accessible at /health/live

  • @Readiness - the readiness check accessible at /health/ready

  • @Startup - the readiness check accessible at /health/started

HealthCheck is a functional interface whose single method call returns a HealthCheckResponse object which can be easily constructed by the fluent builder API shown in the example.

Now it’s time to build and deploy our application that contains this health check to the WildFly server.

WARN: Make sure your WildFly server is started.

$ mvn clean package wildfly:deploy

Now we can simply repeat the request to http://localhost:9990/health/live by refreshing your browser window or by using curl http://localhost:9990/health/live. Because we defined our health check to be a liveness procedure (with @Liveness qualifier) the new health check procedure is now present in the checks array.

Congratulations! You’ve created your first health check procedure. Let’s continue by exploring what else can be done with the MicroProfile Health specification.

Adding a readiness health check procedure

In the previous section, we created a simple liveness health check procedure which states whether our application is running or not. In this section, we will create a readiness health check which will be able to state whether our application is able to process requests.

We will create another health check procedure that simulates a connection to an external service provider such as a database. For starters, we will always return the response indicating the application is ready.

Create org.wildfly.quickstarts.microprofile.health.DatabaseConnectionHealthCheck class:

package org.wildfly.quickstarts.microprofile.health;

import org.eclipse.microprofile.health.HealthCheck;
import org.eclipse.microprofile.health.HealthCheckResponse;
import org.eclipse.microprofile.health.Readiness;

import jakarta.enterprise.context.ApplicationScoped;

@Readiness
@ApplicationScoped
public class DatabaseConnectionHealthCheck implements HealthCheck {

    @Override
    public HealthCheckResponse call() {
        return HealthCheckResponse.up("Database connection health check");
    }
}

Now you can redeploy your application:

$ mvn clean package wildfly:deploy

If you now rerun the health check at http://localhost:9990/health/live the checks array will contain only the previously defined SimpleHealthCheck as it is the only check defined with the @Liveness qualifier. However, if you access http://localhost:9990/health/ready (in the browser or with curl http://localhost:9990/health/ready) you will see only the Database connection health check as it is the only health check defined with the @Readiness qualifier as the readiness health check procedure.

Note
 If you access http://localhost:9990/health you will get back both checks.

More information about which health check procedures should be used in which situation is detailed in the MicroProfile Health specification. Generally, the liveness procedures determine whether the application should be restarted while readiness procedures determine whether it makes sense to contact the application with requests.

Startup health checks

Startup health checks are used in cloud environments to define checks that should respond UP before the liveness checks start to be called. This is useful in cases of slow container startups so the container won’t get prematurely restarted if liveness is called before the container is fully initialized. These checks are defined in the same way as liveness or readiness checks but with the @Startup CDI qualifier. The HTTP endpoint exposed for the startup checks is available at /health/started. For simplicity, we will not include code example in this quickstart.

Negative health check procedures

In this section, we extend our Database connection health check with the option of stating that our application is not ready to process requests as the underlying database connection cannot be established. For simplicity reasons, we only determine whether the database is accessible or not by a configuration property.

To use MicroProfile Config configuration values we first need to add the Config API dependency to our application:

<!-- Import the MicroProfile Config API, we use provided scope as the API is included in the server -->
<dependency>
  <groupId>org.eclipse.microprofile.config</groupId>
  <artifactId>microprofile-config-api</artifactId>
  <scope>provided</scope>
</dependency>

Update the org.wildfly.quickstarts.microprofile.health.DatabaseConnectionHealthCheck class:

package org.wildfly.quickstarts.microprofile.health;

import org.eclipse.microprofile.config.inject.ConfigProperty;
import org.eclipse.microprofile.health.HealthCheck;
import org.eclipse.microprofile.health.HealthCheckResponse;
import org.eclipse.microprofile.health.HealthCheckResponseBuilder;
import org.eclipse.microprofile.health.Readiness;

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;

@Readiness
@ApplicationScoped
public class DatabaseConnectionHealthCheck implements HealthCheck {

    @Inject
    @ConfigProperty(name = "database.up", defaultValue = "false")
    private boolean databaseUp;

    @Override
    public HealthCheckResponse call() {

        HealthCheckResponseBuilder responseBuilder = HealthCheckResponse.named("Database connection health check");

        try {
            simulateDatabaseConnectionVerification();
            responseBuilder.up();
        } catch (IllegalStateException e) {
            // cannot access the database
            responseBuilder.down();
        }

        return responseBuilder.build();
    }

    private void simulateDatabaseConnectionVerification() {
        if (!databaseUp) {
            throw new IllegalStateException("Cannot contact database");
        }
    }
}

Redeploy your application:

$ mvn clean package wildfly:deploy

If you now rerun the readiness health check (at http://localhost:9990/health/ready) the overall status should be DOWN. You can also check the liveness check at http://localhost:9990/health/live which will return the overall status UP because it isn’t influenced by the readiness checks.

As we shouldn’t leave this application with a readiness check in a DOWN state you can add database.up=true in src/main/resources/META-INF/microprofile-config.properties and redeploy the application. The readiness health check should be up again.

Adding user-specific data to the health check response

In previous sections, we saw how to create simple health checks with only the minimal attributes, namely, the health check name and its status (UP or DOWN). However, the MicroProfile specification also provides a way for the applications to supply arbitrary data in the form of key-value pairs sent to the consuming end. This can be done by using the withData(key, value) method of the health check response builder API.

Let’s create a new health check procedure org.wildfly.quickstarts.microprofile.health.DataHealthCheck:

package org.wildfly.quickstarts.microprofile.health;

import org.eclipse.microprofile.health.Liveness;
import org.eclipse.microprofile.health.HealthCheck;
import org.eclipse.microprofile.health.HealthCheckResponse;

import jakarta.enterprise.context.ApplicationScoped;

@Liveness
@ApplicationScoped
public class DataHealthCheck implements HealthCheck {

    @Override
    public HealthCheckResponse call() {
        return HealthCheckResponse.named("Health check with data")
                .up()
                .withData("foo", "fooValue")
                .withData("bar", "barValue")
                .build();
    }
}

If you redeploy and rerun the liveness health check procedure by accessing the /health/live endpoint you can see that the new health check Health check with data is present in the checks array. This check contains a new attribute called data which is a JSON object consisting of the properties we have defined in our health check procedure.

This functionality is specifically useful in failure scenarios where you can pass the error along with the health check response.

        try {
            simulateDatabaseConnectionVerification();
            responseBuilder.up();
        } catch (IllegalStateException e) {
            // cannot access the database
            responseBuilder.down()
                    .withData("error", e.getMessage()); // pass the exception message
        }

Building and running the quickstart application in a bootable JAR

You can use the WildFly JAR Maven plug-in to build a WildFly bootable JAR to run this quickstart.

The quickstart pom.xml file contains a Maven profile named bootable-jar which configures the bootable JAR building:

      <profile>
          <id>bootable-jar</id>
          <build>
              <plugins>
                  <plugin>
                      <groupId>org.wildfly.plugins</groupId>
                      <artifactId>wildfly-jar-maven-plugin</artifactId>
                      <configuration>
                          <feature-pack-location>wildfly@maven(org.jboss.universe:community-universe)#${version.server}</feature-pack-location>
                          <layers>
                              <layer>jaxrs-server</layer>
                              <layer>microprofile-config</layer>
                          </layers>
                          <plugin-options>
                              <jboss-fork-embedded>true</jboss-fork-embedded>
                          </plugin-options>
                      </configuration>
                      <executions>
                          <execution>
                              <goals>
                                  <goal>package</goal>
                              </goals>
                          </execution>
                      </executions>
                  </plugin>
              </plugins>
          </build>
      </profile>
Procedure

  1. Build the quickstart bootable JAR with the following command:

    $ mvn clean package -Pbootable-jar

  2. Run the quickstart application contained in the bootable JAR:

    $ java -jar target/microprofile-health-bootable.jar

  3. You can now interact with the quickstart application.

Note

After the quickstart application is deployed, the bootable JAR includes the application in the root context. Therefore, any URLs related to the application should not have the /microprofile-health path segment after HOST:PORT.

Run the Integration Tests with a bootable jar

The integration tests included with this quickstart, which verify that the quickstart runs correctly, may also be run with a bootable jar.

Follow these steps to run the integration tests.

  1. Make sure the bootable jar is provisioned.

    $ mvn clean package -Pbootable-jar

  2. Start the WildFly bootable jar, this time using the WildFly Maven Jar Plugin, which is recommend for testing due to simpler automation.

    $ mvn wildfly-jar:start -Djar-file-name=target/microprofile-health-bootable.jar

  3. Type the following command to run the verify goal with the integration-testing profile activated, and specifying the quickstart’s URL using the server.host system property, which for a bootable jar by default is http://localhost:8080.

    $ mvn verify -Pintegration-testing -Dserver.host=http://localhost:8080

  4. Shutdown the WildFly bootable jar, this time using the WildFly Maven Jar Plugin too.

    $ mvn wildfly-jar:shutdown

Building and running the quickstart application with OpenShift

Build the WildFly Source-to-Image (S2I) Quickstart to OpenShift with Helm Charts

On OpenShift, the S2I build with Apache Maven uses an openshift Maven profile to provision a WildFly server, deploy and run the quickstart in OpenShift environment.

The server provisioning functionality is provided by the WildFly Maven Plugin, and you may find its configuration in the quickstart pom.xml:

        <profile>
            <id>openshift</id>
            <build>
                <plugins>
                    <plugin>
                        <groupId>org.wildfly.plugins</groupId>
                        <artifactId>wildfly-maven-plugin</artifactId>
                        <configuration>
                            <feature-packs>
                                <feature-pack>
                                    <location>org.wildfly:wildfly-galleon-pack:${version.server}</location>
                                </feature-pack>
                                <feature-pack>
                                    <location>org.wildfly.cloud:wildfly-cloud-galleon-pack:${version.pack.cloud}</location>
                                </feature-pack>
                            </feature-packs>
                            <layers>...</layers>
                            <name>ROOT.war</name>
                        </configuration>
                        <executions>
                            <execution>
                                <goals>
                                    <goal>package</goal>
                                </goals>
                            </execution>
                        </executions>
                    </plugin>
                    ...
                </plugins>
            </build>
        </profile>

You may note that unlike the provisioned-server profile it uses the cloud feature pack which enables a configuration tuned for OpenShift environment.

Getting Started with WildFly for OpenShift and Helm Charts

This section contains the basic instructions to build and deploy this quickstart to WildFly for OpenShift or WildFly for OpenShift Online using Helm Charts.

Prerequisites

  • You must be logged in OpenShift and have an oc client to connect to OpenShift

  • Helm must be installed to deploy the backend on OpenShift.

Once you have installed Helm, you need to add the repository that provides Helm Charts for WildFly.

$ helm repo add wildfly https://docs.wildfly.org/wildfly-charts/
"wildfly" has been added to your repositories
$ helm search repo wildfly
NAME                    CHART VERSION   APP VERSION     DESCRIPTION
wildfly/wildfly         ...             ...            Build and Deploy WildFly applications on OpenShift
wildfly/wildfly-common  ...             ...            A library chart for WildFly-based applications

Deploy the WildFly Source-to-Image (S2I) Quickstart to OpenShift with Helm Charts

Log in to your OpenShift instance using the oc login command. The backend will be built and deployed on OpenShift with a Helm Chart for WildFly.

Navigate to the root directory of this quickstart and run the following command:

$ helm install microprofile-health -f charts/helm.yaml wildfly/wildfly --wait --timeout=10m0s
NAME: microprofile-health
...
STATUS: deployed
REVISION: 1

This command will return once the application has successfully deployed. In case of a timeout, you can check the status of the application with the following command in another terminal:

oc get deployment microprofile-health

The Helm Chart for this quickstart contains all the information to build an image from the source code using S2I on Java 17:

build:
  uri: https://github.com/wildfly/quickstart.git
  ref: 32.x
  contextDir: microprofile-health
deploy:
  replicas: 1

This will create a new deployment on OpenShift and deploy the application.

If you want to see all the configuration elements to customize your deployment you can use the following command:

$ helm show readme wildfly/wildfly

Get the URL of the route to the deployment.

$ oc get route microprofile-health -o jsonpath="{.spec.host}"

Access the application in your web browser using the displayed URL.

Note

The Maven profile named openshift is used by the Helm chart to provision the server with the quickstart deployed on the root web context, and thus the application should be accessed with the URL without the /microprofile-health path segment after HOST:PORT.

This quickstart requires the management port (9990) to be exposed for demo purposes and testing. We do this only to demonstrate the concepts and ease the testing.

Important
 It is not recommended to expose the management port in a production environment!

To expose the management porte to manually exposes our service on port 9990 we deploying the following file:

oc apply -f charts/management.yml

Once this is deployed you will be able to access the management port via the created microprofile-health-management route.

To get the address of the microprofile-health-management route, execute:

$ oc get route microprofile-health -o jsonpath="{.spec.host}"

Run the Integration Tests with OpenShift

The integration tests included with this quickstart, which verify that the quickstart runs correctly, may also be run with the quickstart running on OpenShift.

Note

The integration tests expect a deployed application, so make sure you have deployed the quickstart on OpenShift before you begin.

This quickstart requires the management port (9990) to be exposed for demo purposes and testing. We do this only to demonstrate the concepts and ease the testing.

Important
 It is not recommended to expose the management port in a production environment!

To expose the management porte to manually exposes our service on port 9990 we deploying the following file:

oc apply -f charts/management.yml

Once this is deployed you will be able to access the management port via the created microprofile-health-management route.

To get the address of the microprofile-health-management route, execute:

$ oc get route microprofile-health -o jsonpath="{.spec.host}"

Run the integration tests using the following command to run the verify goal with the integration-testing profile activated and the proper URL:

$ mvn verify -Pintegration-testing -Dserver.host=https://$(oc get route microprofile-health --template='{{ .spec.host }}') -Dserver.management.host=https://$(oc get route microprofile-health-management --template='{{ .spec.host }}')
Note

The tests are using SSL to connect to the quickstart running on OpenShift. So you need the certificates to be trusted by the machine the tests are run from.

Undeploy the WildFly Source-to-Image (S2I) Quickstart from OpenShift with Helm Charts

$ helm uninstall microprofile-health

Conclusion

MicroProfile Health provides a way for your application to distribute information about its healthiness state to state whether or not it is able to function properly. Liveness checks are utilized to tell whether the application should be restarted. Readiness checks are used to tell whether the application is able to process requests. And last but not least, startup checks are useful if your container has a slow startup to prevent premature restarts if the liveness probes are called too soon.

Congratulations! You have reached the end of this tutorial. You can find more information about the MicroProfile Health in the specification github repository.