Chapter 25. Eclipse MicroProfile

Configuration data can change dynamically and applications need to be able to access the latest configuration information without restarting the server. Eclipse MicroProfile Config provides portable externalization of configuration data. This allows applications and microservices to be configured to run in multiple environments without a need for modification or repackaging. Eclipse MicroProfile Config functionality is implemented in JBoss EAP using the SmallRye Config component and is provided by the microprofile-config-smallrye subsystem. This subsystem is included in the default JBoss EAP 7.2 configuration.

MicroProfile Config configuration properties, which can be in different formats and can come from different locations, are provided by ConfigSources, which are implementations of the org.eclipse.microprofile.config.spi.ConfigSource interface.

The MicroProfile Config specification provides the following default ConfigSource implementations for retrieving configuration values.

The microprofile-config-smallrye subsystem supports the following additional types of ConfigSource resources for retrieving configuration values.

See MicroProfile Config SmallRye Subsystem Attributes for the list of attributes available for configuring the MicroProfile Config SmallRye subsystem.

Obtaining ConfigSource Configuraton from Properties

You can store properties directly for access by a ConfigSource by adding a config-source attribute and specifying the properties as a list.

The following management CLI command creates a ConfigSource containing configuration data for the property1 and property2 properties.

/subsystem=microprofile-config-smallrye/config-source=props:add(properties={property1=value1,property2=value2})

This command results in the following XML configuration for the microprofile-config-smallrye subsystem.

<subsystem xmlns="urn:wildfly:microprofile-config-smallrye:1.0">
    <config-source name="props">
        <property name="property1" value="value1"/>
        <property name="property2" value="value2"/>
    </config-source>
</subsystem>

Obtaining ConfigSource Configuraton from a Directory

You can create a ConfigSource to read properties from files in a directory by adding the config-source attribute and specifying the directory that contains the files. The name of each file in the dir directory is the name of a property and the file content is the value of the property,

The following management CLI command creates a ConfigSource that reads configuration properties from files in the /etc/config/numbers-app/ directory.

/subsystem=microprofile-config-smallrye/config-source=file-props:add(dir={path=/etc/config/numbers-app})

This command results in the following XML configuration for the microprofile-config-smallrye subsystem.

<subsystem xmlns="urn:wildfly:microprofile-config-smallrye:1.0">
    <config-source name="file-props">
        <dir path="/etc/config/numbers-app"/>
    </config-source>
</subsystem>

This structure corresponds to the structure used by OpenShift ConfigMaps. The dir value corresponds to the mountPath in the ConfigMap definition in OpenShift or Kubernetes.

Any application deployed in JBoss EAP can programmatically access the properties that are stored in the directory.

Assume that the directory /etc/config/numbers-app/ contains the following two files:

In the code example below, num.size returns 5 and num.max returns 100.

@Inject
@ConfigProperty(name = "num.size")
int numSize;

@Inject
@ConfigProperty(name = "num.max")
int numMax;

Obtaining ConfigSource Configuraton from a ConfigSource Class

You can create and configure a custom org.eclipse.microprofile.config.spi.ConfigSource implementation class to provide a source for the configuration values.

The following management CLI command creates a ConfigSource for the implementation class named org.example.MyConfigSource that is provided by a JBoss Module named org.example.

/subsystem=microprofile-config-smallrye/config-source=my-config-source:add(class={name=org.example.MyConfigSource, module=org.example})

This command results in the following XML configuration for the microprofile-config-smallrye subsystem.

<subsystem xmlns="urn:wildfly:microprofile-config-smallrye:1.0">
    <config-source name="my-config-source">
        <class name="org.example.MyConfigSource" module="org.example"/>
    </config-source>
</subsystem>

Properties provided by this ConfigSource class are available to any JBoss EAP deployment.

For information about how to add a global module to the JBoss EAP server, see Define Global Modules.

Obtaining ConfigSource Configuraton from a ConfigSourceProvider Class

You can create and configure a custom org.eclipse.microprofile.config.spi.ConfigSourceProvider implementation class that registers implementations for multiple ConfigSource instances.

The following management CLI command creates a config-source-provider for the implementation class named org.example.MyConfigSourceProvider that is provided by a JBoss Module named org.example.

/subsystem=microprofile-config-smallrye/config-source-provider=my-config-source-provider:add(class={name=org.example.MyConfigSourceProvider, module=org.example})

This command results in the following XML configuration for the microprofile-config-smallrye subsystem.

<subsystem xmlns="urn:wildfly:microprofile-config-smallrye:1.0">
    <config-source-provider name="my-config-source-provider">
         <class name="org.example.MyConfigSourceProvider" module="org.example"/>
    </config-source-provider>
</subsystem>

Properties provided by the ConfigSourceProvider implementation are available to any JBoss EAP deployment.

For information about how to add a global module to the JBoss EAP server, see Define Global Modules.

Applications that access MicroProfile Config in their Java code must enable CDI, either by including a META-INF/beans.xml or WEB-INF/beans.xml file in the deployment archive, or by including a CDI bean annotation.

For more information about CDI, see Contexts and Dependency Injection (CDI) in the JBoss EAP Development Guide.

The ability to trace requests across service boundaries is important, especially in a microservices environment where a request can flow through multiple services during its life cycle. The Eclipse Microprofile OpenTracing specification defines behaviors and an API for accessing an OpenTracing compliant Tracer object within a JAX-RS application. The behaviors specify how OpenTracing Spans are to be created automatically for incoming and outgoing requests. The API defines how to explicitly disable or enable tracing for given endpoints.

Eclipse Microprofile OpenTracing functionality is implemented in JBoss EAP using the SmallRye OpenTracing component and is provided by the microprofile-opentracing-smallrye subsystem. This subsystem implements Microprofile 1.1, which includes support for tracing requests to JAX-RS endpoints and CDI beans and is included in the default JBoss EAP 7.2 configuration.

The microprofile-opentracing-smallrye subsystem ships with the Jaeger Java Client as the default tracer, plus a set of instrumentation libraries for components commonly used in Java EE applications, such as JAX-RS and CDI. Each individual WAR deployed to the JBoss EAP server automatically has its own Tracer instance. Each WAR within an EAR is treated as an individual WAR, and each has its own Tracer instance. By default, the service name used with the Jaeger Client is derived from the deployment’s name, which is usually the WAR file name.

The microprofile-opentracing-smallrye subsystem is included in the default JBoss EAP 7.2 configuration. Because there can be a memory or performance costs associated with OpenTracing enabled, you might want to disable this subsystem.

Use the following management CLI commands to disable the MicroProfile OpenTracing feature globally for the server instance by removing the subsystem from the server configuration.

Use the following management CLI commands to enable the MicroProfile OpenTracing feature globally for the server instance by adding the subsystem to the server configuration.

There are no other configuration options available for the microprofile-opentracing-smallrye subsystem. Instead, you configure the Jaeger Client by setting system properties or environment variables. See the Jaeger documentation for information about how to configure the Jaeger Client. See Configuration via Environment in the Jaeger documentation for the list of valid system properties.

For information about how to override the default tracer and how to trace CDI beans, see Using Eclipse MicroProfile OpenTracing to Trace Requests in the Development Guide.

JBoss EAP includes the SmallRye Health component, which provides Eclipse MicroProfile Health functionality using the microprofile-health-smallrye subsystem. This subsystem is used to determine if the JBoss EAP instance is responding as expected, and is enabled by default.

Health checks can be examined using the management CLI. The following command demonstrates obtaining the current health of the server.

/subsystem=microprofile-health-smallrye:check
{
    "outcome" => "success",
    "result" => {
        "outcome" => "UP",
        "checks" => []
    }
}

Health check is automatically deployed to the health context on JBoss EAP. That means that in addition to being able to examine it using the management CLI, you can also obtain the current health using the HTTP endpoint. The default address for the /health endpoint, accessible from the management interfaces, is http://127.0.0.1:9990/health.

To obtain the current health of the server using the HTTP endpoint, the following URL would be used.

http://HOST:PORT/health

Accessing this context displays the health check in JSON format, indicating if the server is healthy.

Enable Authentication for the HTTP Endpoint

The health context can be configured to require that users be authorized to access the context. The following procedure enables authentication on this endpoint.

Any subsequent attempts to access the health endpoint will now result in an authentication prompt.