Backporting compatibility of Microprofile Health-4.0 and introducing file-based health checks in 25.0.0.6-beta

Navaneeth S Nair on Jun 3, 2025

announcements , microprofile , java-se , release , beta , monitoring ,

Post available in languages:

This beta release brings updates to backporting compatibility of mpHealth-4.0 and file-based health checks that were earlier released in 25.0.0.4-beta. This feature performs health checks on applications deployed to the server, allowing automated services to check availability and responsiveness during runtime.

Backporting compatibility of mpHealth-4.0 for Java EE7 and EE8 environments and introducing file-based health checks

In the previous 25.0.0.4-beta release, the Open Liberty server introduced the file-based health check mechanism for a MicroProfile Health 4.0 feature (mpHealth-4.0). In 25.0.0.4-beta, the configuration for this mechanism was introduced with the server.xml attribute fileUpdateInterval for the <mpHealth> element with an associated MP_HEALTH_FILE_UPDATE_INTERVAL environment variable. The configuration attribute has now been updated to checkInterval with an associated MP_HEALTH_CHECK_INTERVAL environment variable. Similar to before, this attribute needs to be configured to enable this alternative file-based health check mechanism. The configuration accepts a number followed by an optional ms or s to denote the time unit. If no time unit is specified, it defaults to seconds. Invalid values default the interval to 10 s.

This beta now introduces a new server.xml attribute for the <mpHealth> element named startupCheckInterval with an associated MP_HEALTH_STARTUP_CHECK_INTERVAL environment variable. This configuration is optional and defaults to 100 ms if the user has not configured it. The configuration accepts a number followed by an optional ms or s to denote the time unit. If no time unit is specified, it defaults to milliseconds. Invalid values default the interval to 100 ms.

The startupCheckInterval is used during the startup phase of the file-based health check mechanism. As a refresher, the file-based health check functionality creates the live, ready, and started files under the ${server.output.dir}/health directory. The ${server.output.dir} defaults to wlp/usr/servers/<server>. For more information, see directory locations and properties.

These files are created when their respective health checks return an UP status. The startupCheckInterval is the interval at which the runtime queries the health checks during the startup phase. When all statuses report UP then all three started, ready and live files are created. Next, we proceed to the update phase. At this point, the started file is no longer needed, as its purpose is to indicate that all application startup health checks have been completed successfully. After Kubernetes has found an UP status, it proceeds to start its checks for liveness and readiness. It’s at this point when the checkInterval is used by the runtime to establish the interval at which the liveness and readiness health checks are queried. Similar to before, if an UP status is resolved then the respective health-check file is updated (that is, the last modified time of the file is updated). A DOWN status results in the respective health-check file not being updated.

The following example shows the server.xml configuration with both configurations: Note that only checkInterval is required to enable the functionality and the startupCheckInterval is optional as it defaults to 100 ms. The startupCheckInterval is faster compared to the checkInterval to allow for the creation of the files as soon as possible.

<server>
  <features>
    <feature>mphealth-4.0</feature>
  </features>
  <mpHealth checkInterval="10s" startupCheckInterval="150ms"/>
</server>

With file-based checks, the exec command strategy can be used instead of the httpGet or gRPC strategy when configuring the Kubernetes health check probes. In this beta, scripts are introduced into the Open Liberty image for these file-based health checks.

The scripts are startupHealthCheck.sh, livenessHealthCheck.sh and readinessHealthCheck.sh. For the startupHealthCheck.sh script, it is important to pass in the option -t or --timeout-seconds with a value that matches the timeoutSeconds configuration of the startup probe.

Similarly, for the livenessHealthCheck.sh and readinessHealthCheck.sh, a -p or --period-seconds option should be passed in with the value used for the periodSeconds configuration of the respective liveness and readiness probe. The liveness and readiness health check scripts check that the respective live and ready files have been updated within the past period seconds.

For best results, configure the liveness and readiness probes to at least 1.5 times greater than the checkInterval configuration.

For example, if an Open Liberty application image is configured and deployed where the checkInterval attribute is set to 10 seconds, a Kubernetes configuration similar to the following example can be used:

  probes:
    startup:
      exec:
        command:
          - /bin/sh
          - '-c'
          - startupHealthCheck.sh -t 1
      failureThreshold: 8
      initialDelaySeconds: 0
      periodSeconds: 1
      timeoutSeconds: 1
    liveness:
      exec:
        command:
          - /bin/sh
          - '-c'
          - livenessHealthCheck.sh -p 15
      failureThreshold: 3
      initialDelaySeconds: 0
      periodSeconds: 15
      timeoutSeconds: 5
    readiness:
      exec:
        command:
          - /bin/sh
          - '-c'
          - readinessHealthCheck.sh -p 15
      failureThreshold: 3
      initialDelaySeconds: 0
      periodSeconds: 15
      timeoutSeconds: 5

Notice that in the liveness and readiness probes, the periodSeconds is set to 15, or 1.5x the checkInterval.

Try it now

To try out these features, update your build tools to pull the Open Liberty All Beta Features package instead of the main release. The beta works with Java SE 21, Java SE 17, Java SE 11, and Java SE 8.

If you’re using Maven, you can install the All Beta Features package using:

<plugin>
    <groupId>io.openliberty.tools</groupId>
    <artifactId>liberty-maven-plugin</artifactId>
    <version>3.11.3</version>
    <configuration>
        <runtimeArtifact>
          <groupId>io.openliberty.beta</groupId>
          <artifactId>openliberty-runtime</artifactId>
          <version>25.0.0.6-beta</version>
          <type>zip</type>
        </runtimeArtifact>
    </configuration>
</plugin>

Don’t forget to add dependencies to your pom.xml file for the beta version of the APIs that are associated with the beta features that wanted to be tried. For example, the following block adds dependencies for two example beta APIs:

<dependency>
    <groupId>org.example.spec</groupId>
    <artifactId>exampleApi</artifactId>
    <version>7.0</version>
    <type>pom</type>
    <scope>provided</scope>
</dependency>
<dependency>
    <groupId>example.platform</groupId>
    <artifactId>example.example-api</artifactId>
    <version>11.0.0</version>
    <scope>provided</scope>
</dependency>

Or for Gradle:

buildscript {
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath 'io.openliberty.tools:liberty-gradle-plugin:3.9.3'
    }
}
apply plugin: 'liberty'
dependencies {
    libertyRuntime group: 'io.openliberty.beta', name: 'openliberty-runtime', version: '[25.0.0.6-beta,)'
}

Or if you’re using container images:

FROM icr.io/appcafe/open-liberty:beta

Or take a look at our Downloads page.

If you’re using IntelliJ IDEA, Visual Studio Code or Eclipse IDE, you can also take advantage of our open source Liberty developer tools to enable effective development, testing, debugging and application management all from within your IDE.

For more information on using a beta release, refer to the Installing Open Liberty beta releases documentation.

We welcome your feedback

Let us know what you think on our mailing list. If you hit a problem, post a question on StackOverflow. If you hit a bug, please raise an issue.

See all blog posts