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

[Channyboy]

The information you provide here will be included in the Open Liberty beta blog post (example), which will be published on openliberty.io/blog/, and potentially elsewhere, to promote this beta feature/function of Open Liberty. For this post to be included in the beta issue please make sure that this is completed by the end of Friday following the GM (Tuesday). The beta and release blogs are created using automation and rely on you following the template's structure. DO NOT REMOVE/ALTER THE <GHA> TAGS THROUGHOUT THIS TEMPLATE.

<GHA-BLOG-SUMMARY>

Please provide a summary of the update, including the following points:

• A sentence or two that introduces the update to someone new to the general technology/concept.

The mpHealth-4.0 feature enables a MicroProfile Health 4.0 runtime for the OpenLiberty server which until now only supported running under an environment that is on the Jakarta EE 9 (or higher) platform. In this beta release, the mpHealth-4.0 feature is now compatible to run on Java EE7 and EE8 environments. Additionally, we've introduced a file-based health check mechanism as an alternative health checking strategy to the the /health/* REST endpoints.

• The Human-readable name and short feature name for your feature- eg WebSockets feature (websockets-1.0).

  mpHealth-4.0

• Who is the target persona? Who do you expect to use the update? eg application developer, operations.

  Operations

• What was the problem before and how does your update make their life better? (Why should they care?)

The Microprofile Health technology is best leveraged when the application is deployed onto a Kubernetes based environment where Liveness, Readiness and Startup Probes can be used. In such a deployment scenario, it can possible that the applications deployed may be on different Java and Jakarta EE levels. This can result in a mixture of mpHealth-x.x features across different servers and different Kubernetes probe configurations. To provide technological concurrency for users and to unify OpenLibety server configurations and Kubernetes Health Check probe configurations the mpHealth-4.0 feature is now compatible for use with Java EE7 and Java EE8 alongside it's existing support for Jakarta EE9 and Jakarta EE10 environments.

In addition to the existing strategy of querying the /health/live, /health/ready, /health/started REST endpoints we have introduced a file-based health check functionality as an alternative. The files live, ready, and started will be created under the <server.output.dir>/health directory. The <server.output.dir> defaults to wlp/usr/servers/<server>, see Directory locations and properties for more information. The started file will be created when the application(s)' startup health checks return an UP status . Similarly, the live and ready files will be created when the application(s)' liveness and readiness health checks return an UP status. The runtime will then continue query the liveness and readiness health checks at a use-defined interval. If the status returns UP the file will have it's last modified time updated. If a file has not been updated then it indicates that a DOWN status was returned. This file-based functionality is only enabled if a user configures the fileUpdateInterval configuration attribute for the mpHealth configuration element. Or if the environment variable MP_HEALTH_FILE_UPDATE_INTERVAL is used. Note that if both environment variable and the server.xml is configured, the server.xml takes precedence during runtime.

The configuration accepts a number followed by an optional ms or s to denote the time unit. If no time unit is specified, it will default to seconds. Invalid values will default the interval to 10 seconds.

For example:

<server>
  <features>
    <feature> mphealth-4.0</feature>
  </features>

  <mpHealth fileUpdateInterval="10s"
</server>

This new functionality allows users to use the exec command strategy instead of the httpGet, or perhaps gRPC, strategy when configuring the Kubernetes health check probes configuration. To best use this new functionality, we recommend that the startup probe is configured to check for the existence of the started file. For the liveness and readiness probes, we recommend that the probe interval is at-least 1.5 times greater than the fileUpdateInterval configuration. The exec command should check for the existence of the file and check if the file has been modified within duration of the probe interval. Note that the <server.output.dir> in an OpenLibety container is /opt/ol/wlp/output/defaultServer or simply /output

For example, if we have configured and deployed an OpenLiberty application image where the mpHealth-4.0's fileUpdateInterval was set to 10 seconds we can use a Kubernetes configuration that looks similar to this:

  probes:
    startup:
      exec:
        command:
          - /bin/sh
          - '-c'
          - file=/output/health/started; cat $file
      failureThreshold: 5
      initialDelaySeconds: 15
      periodSeconds: 15
      timeoutSeconds: 5
    liveness:
      exec:
        command:
          - /bin/sh
          - '-c'
          - file=/output/health/live; x=$(cat $file) && mts=$(stat --format=%.3Y $file | tr -d ".") && if [ $(expr $(date +%s%3N) - $mts) -gt 15000 ] ; then (exit 1) ; else (exit 0) ; fi
      failureThreshold: 3
      initialDelaySeconds: 10
      periodSeconds: 15
      timeoutSeconds: 5
    readiness:
      exec:
        command:
          - /bin/sh
          - '-c'
          - file=/output/health/ready; x=$(cat $file) && mts=$(stat --format=%.3Y $file | tr -d ".") && if [ $(expr $(date +%s%3N) - $mts) -gt 15000 ] ; then (exit 1) ; else (exit 0) ; fi
      failureThreshold: 3
      initialDelaySeconds: 10
      periodSeconds: 15
      timeoutSeconds: 5

Notice that in the liveness and readiness probes, we have set the periodSeconds to 15 (i.e., 1.5x the fileUpdateInterval) and the check that the file was last modified within the 15 seconds (i.e., the -gt 15000 part of the command) .

• Briefly explain how to make your update work. Include screenshots, diagrams, and/or code snippets, and provide a server.xml snippet.
  Combined it with the above bit
• Where can they find out more about this specific update (eg Open Liberty docs, Javadoc) and/or the wider technology?

</GHA-BLOG-SUMMARY>

What happens next?

• Add the label to the blog issue for the beta you're targeting (e.g. target:YY00X-beta).
• Make sure this blog post is linked back to the Epic for this feature/function.
• Your paragraph will be included in the beta blog post. It might be edited for style and consistency.
• You will be asked to review a draft before publication.
  • Once you've approved the code review, close this issue.
• If you would also like to write a standalone blog post about your update (highly recommended), raise an issue on the Open Liberty blogs repo. State in the issue that the blog post relates to a specific release so that we can ensure it is published on an appropriate date (it won't be the same day as the beta blog post).