The microprofile-config quickstart demonstrates the use of the MicroProfile Config specification in WildFly.

What is it?

MicroProfile Config allows users to externalize their configuration from their application code. Users can modify the configuration from outside of the application so they can change it without the need to rebuild their applications. It exposes the configuration values to the application code through the CDI injection.

Architecture

In this quickstart, we have a collection of CDI beans that expose functionalities of the MicroProfile Config specification. The individual externally configured values are provided to the users through a set of REST endpoints.

Browse the source

System Requirements

The application this project produces is designed to be run on WildFly Application Server 33 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-config/target/microprofile-config.war to the running instance of the server.

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

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

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

Creating the Maven Project

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

Open the project in your favourite IDE.

Open the generated pom.xml:

The first thing to do is 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>33.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 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>
<!-- 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>
<!-- Import the Jakarta REST API, we use provided scope as the API is included in the server -->
<dependency>
  <groupId>jakarta.ws.rs</groupId>
  <artifactId>jakarta.ws.rs-api</artifactId>
  <scope>provided</scope>
</dependency>
Note
 Because MicroProfile Config uses CDI injection to expose configuration values to the user application we need to also include the CDI API dependency.

All dependencies can have provided scope.

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>

As this is a Jakarta REST application we need to also create an application class. Create org.wildfly.quickstarts.microprofile.config.JaxRsApplication with the following content:

Note
 The new file should be created in src/main/java/org/quickstarts/microprofile/config/JaxRsApplication.java. 
package org.wildfly.quickstarts.microprofile.config;

import jakarta.ws.rs.ApplicationPath;
import jakarta.ws.rs.core.Application;

@ApplicationPath("/")
public class JaxRsApplication extends Application {
}

Now we are ready to start working with MicroProfile Config.

Injecting a configuration value

Let’s start by creating a new CDI bean which will use for the injection of our configuration values. This CDI bean will also be a JAX-RS resource. Create a new class org.wildfly.quickstarts.microprofile.config.ConfigResource;

To inject any configuration value, MicroProfile Config provides a custom qualifier ConfigProperty:

package org.wildfly.quickstarts.microprofile.config;

import org.eclipse.microprofile.config.inject.ConfigProperty;

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;

@Path("/config")
@ApplicationScoped
public class ConfigResource {

    @Inject
    @ConfigProperty(name = "config.prop")
    private String configValue;

    @GET
    @Path("/value")
    public String getValue() {
        return configValue;
    }
}

As you can see, we are injecting a String configuration value named config.prop directly into our CDI bean (annotated with @ApplicationScoped) which is also at the same time a REST endpoint.

Let’s try to deploy this application to the application server. There are several ways of how you can specify the value of your configuration properties which the specification calls config sources. By default each MicroProfile Config implementation must provide at least three default config sources:

  • System properties

  • Environment properties

  • META-INF/microprofile-config.properties file

If the same configuration value is defined by several config sources at the same time, it is resolved based on the config sources priority. The default config sources are prioritized in descending order (system properties, environment properties, and microprofile-config.properties). So we look for the configuration value in the environment properties only if we cannot find it in the system properties.

Now we can start configuring our application. As specified above, the lowest ranking of the default config sources has the microprofile-config.properties file. So let’s create a new file in our src/main/resources/META-INF/microprofile-config.properties with the following content:

config.prop=MyPropertyFileConfigValue

Now we can test our application correctly recognizes the configuration value:

  • Start your WildFly server

  • Package and deploy your application:

$ mvn clean package wildfly:deploy

To check that the WildFly is working as expected:

You will see that the returned value is our configured system property MyPropertyFileConfigValue.

As said above, there are three different default config sources. So far we have seen only the microprofile-config.properties file which has the lowest priority. Let’s override our configuration value with an environment property which has a bigger priority:

You can see that our configuration value defined in the configuration file was now overridden by the environment property and the value MyEnvPropConfigValue is returned.

The last default config source is the system properties which has the highest priority:

The configuration property was overriden again and the value MySysPropConfigValue is returned.

We covered the basic injection and the default config sources provided by the MicroProfile Config specification. Let’s see what else the MicroProfile Config can offer.

Different types of configuration injections and default values

In our first example we injected a concrete String value:

@Inject
@ConfigProperty(name = "config.prop")
private String configValue;

The ConfigProperty qualifier contains one more optional parameter called the defaultValue. As the name says, this parameter sets the default value if the configuration property is not found in any of the config sources.

To demonstrate how this works, let’s define a new configuration property without the default value:

  • Add the following code to org.wildfly.quickstarts.microprofile.config.ConfigResource:

@Inject
@ConfigProperty(name = "required.prop")
private String requiredProp;

@GET
@Path("/required")
public String getRequiredProp() {
    return requiredProp;
}

  • Build and redeploy the application

$ mvn clean package wildfly:deploy

The deployment will fail with the following error:

Caused by: org.jboss.weld.exceptions.DeploymentException: No Config Value exists for required property required.prop

because the required configuration property required.prop wasn’t defined. Let’s fix this by providing a default value for this property if it’s not found in any of the config sources:

@Inject
@ConfigProperty(name = "required.prop", defaultValue = "Default required prop value")
private String requiredProp;

Build and redeploy the application

$ mvn clean package wildfly:deploy

The application should now deploy without any errors and if access the http://localhost:8080/microprofile-config/config/required endpoint using your browser or curl http://localhost:8080/microprofile-config/config/required you will see the default value that we configured in the ConfigProperty qualifier.

However, this is not the only way how you can deal with the situation when the configuration value is not provided. MicroProfile Config allows you to define different types of injections:

  • concrete values (String, int, double, …​) — see the default converters later

  • optional values (Optional<T>) — if the value is not found the specification injects Optional.empty() so the application can still be successfully deployed even if the configuration property is undefined

  • always reloaded values (Provider<T>) — the value will be reevaluated with every access (see later with custom config sources)

Let’s add a new configuration property optional.prop with the type Optional<String> and corresponding endpoint:

@Inject
@ConfigProperty(name = "optional.prop")
private Optional<String> optionalString;

@GET
@Path("/optional")
public String getOptionalValue() {
    return optionalString.orElse("no optional value provided, use this as the default");
}

Build and redeploy the application

$ mvn clean package wildfly:deploy

If you now access the http://localhost:8080/microprofile-config/config/optional endpoint using your browser or curl http://localhost:8080/microprofile-config/config/optional you will get back the orElse value because the optional.prop was not defined in our config sources.

Last but not least, MicroProfile Config also allows you to inject the whole configuration collected from all config sources as a single object instance of the Config interface which provides a programmatic access to the configuration. Add the following code to org.wildfly.quickstarts.microprofile.config.ConfigResource:

@Inject
private Config config;

@GET
@Path("/all-props")
public String getConfigPropertyNames() {
    return config.getPropertyNames().toString();
}

Build and redeploy the application

$ mvn clean package wildfly:deploy

Access the http://localhost:8080/microprofile-config/config/all-props endpoint using your browser or curl http://localhost:8080/microprofile-config/config/all-props and you will see all available configuration property names.

Note
 You can investigate also the other methods of the Config interface.

Custom configuration sources

MicroProfile Config allows you to define your own custom configuration sources to extend the three default ones provided by the implementation. To define your custom configuration source you need to provide a class which implements either org.eclipse.microprofile.config.spi.ConfigSource or org.eclipse.microprofile.config.spi.ConfigSourceProvider and define it through the service file which will be detected and installed at application startup/deployment.

Let’s define a custom config source with some predefined values. First create a new REST resource org.wildfly.quickstarts.microprofile.config.CustomConfigResource which will be enclosing our custom configurations:

package org.wildfly.quickstarts.microprofile.config;

import org.eclipse.microprofile.config.inject.ConfigProperty;

import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;

@Path("/custom-config")
public class CustomConfigResource {

    @Inject
    @ConfigProperty(name = "custom.config.source.prop")
    private String customConfigSourceProp;

    @GET
    @Path("/value")
    public String getCustomConfigSourceProp() {
        return customConfigSourceProp;
    }
}

Let’s now define a custom configuration source that will provide custom.config.source.prop configuration property. Create a new class org.wildfly.quickstarts.microprofile.config.custom.CustomConfigSource:

package org.wildfly.quickstarts.microprofile.config.custom;

import org.eclipse.microprofile.config.spi.ConfigSource;

import java.util.HashMap;
import java.util.Map;

public class CustomConfigSource implements ConfigSource {

    private final Map<String, String> properties;

    public CustomConfigSource() {
        properties = new HashMap<>();
        properties.put("custom.config.source.prop", "MyCustomValue");
    }

    @Override
    public Map<String, String> getProperties() {
        return properties;
    }

    @Override
    public String getValue(String propertyName) {
        return properties.get(propertyName);
    }

    @Override
    public String getName() {
        return "Custom Config Source with predefined values";
    }

    @Override
    public int getOrdinal() {
        return 400;
    }
}

We only need to override the necessary methods required to get the properties and to set the config source name. In this example, we also override the getOrdinal method which sets the config source priority to be higher than any of the default config sources.

The last thing we need to do is to include our custom configuration source service loader definition. Create src/main/resources/META-INF/services/org.eclipse.microprofile.config.spi.ConfigSource with the following content: org.wildfly.quickstarts.microprofile.config.custom.CustomConfigSource.

Build and redeploy the application

$ mvn clean package wildfly:deploy

If you now access the http://localhost:8080/microprofile-config/custom-config/value endpoint using your browser or curl http://localhost:8080/microprofile-config/custom-config/value you will get back the configuration value MyCustomValue defined in our custom configuration source.

If you would like to have a more programmatic approach to the definition of different ConfigSources, you can use org.eclipse.microprofile.config.spi.ConfigSourceProvider. Let’s create a ConfigSourceProvider that defines a dynamic ConfigSource. Create a new class org.wildfly.quickstarts.microprofile.config.custom.CustomPropertiesFileProvider:

package org.wildfly.quickstarts.microprofile.config.custom;

import org.eclipse.microprofile.config.spi.ConfigSource;
import org.eclipse.microprofile.config.spi.ConfigSourceProvider;

import java.io.FileInputStream;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.Properties;
import java.util.stream.Collectors;

public class CustomPropertiesFileProvider implements ConfigSourceProvider {

    @Override
    public Iterable<ConfigSource> getConfigSources(ClassLoader forClassLoader) {
        List<ConfigSource> configSources = new ArrayList<>();

        configSources.add(new ConfigSource() {
            @Override
            public Map<String, String> getProperties() {
                return reloadPropertiesFile();
            }

            @Override
            public String getValue(String propertyName) {
                return reloadPropertiesFile().get(propertyName);
            }

            @Override
            public String getName() {
                return "Custom dynamic configuration source";
            }
        });

        return configSources;
    }

    private Map<String, String> reloadPropertiesFile() {
        Properties properties = new Properties();
        Path customPropertiesPath = Paths.get(System.getenv("JBOSS_HOME") + "/custom.properties");

        if (!Files.exists(customPropertiesPath)) {
            return new HashMap<>();
        }

        try (FileInputStream is = new FileInputStream(customPropertiesPath.toFile())) {
            properties.load(is);
        } catch (Exception e) {
            throw new RuntimeException(e);
        }

        return properties.entrySet().stream().collect(
            Collectors.toMap(
                entry -> entry.getKey().toString(),
                entry -> entry.getValue().toString()
            )
        );
    }
}
Important
 This requires that the JBOSS_HOME environment variable is set.
Note
 Note that our new custom ConfigSource reloads the property file on every access.

As you can see above, our custom configuration source is accessing a file named custom.properties which needs to be created in your WildFly root directory (JBOSS_HOME):

custom.provided.prop=FileSystemCustomConfigValue

And as previously we need the service loader definition src/main/resources/META-INF/services/org.eclipse.microprofile.config.spi.ConfigSourceProvider with the content: org.wildfly.quickstarts.microprofile.config.custom.CustomPropertiesFileProvider.

Let’s define a new endpoint for accessing this custom dynamic config source. Add the following code to the org.wildfly.quickstarts.microprofile.config.CustomConfigResource:

@Inject
@ConfigProperty(name = "custom.provided.prop", defaultValue = "default")
private Provider<String> providedCustomProp;

@GET
@Path("/reloaded-value")
public String providedCustomProp() {
    return providedCustomProp.get();
}

Note that we are now using jakarta.inject.Provider as an injected type. This means that our value will be reloaded from config sources on every access. Since we are reloading the property file from the file system on every access this allows us to change the configuration dynamically without the need to restart the WildFly server or to redeploy the application.

Build and redeploy the application:

$ mvn clean package wildfly:deploy

If you now access the http://localhost:8080/microprofile-config/custom-config/reloaded-value endpoint using your browser or curl http://localhost:8080/microprofile-config/custom-config/reloaded-value you will get back the configuration value FileSystemCustomConfigValue defined in our custom configuration file. But if you now change the custom.properties file (without stopping of the server or the need to redeploy the application) and repeat the invocation at http://localhost:8080/microprofile-config/custom-config/reloaded-value you will see that the value is dynamically reloaded:

  • change $JBOSS_HOME/custom.properties (don’t forget to save the file):

custom.provided.prop=DynamicallyUpdatedValue

You will see that the value DynamicallyUpdatedValue is returned. If you repeat this with different values of custom.provide.prop it will always get reloaded.

Custom configuration converters

The MicroProfile Config provides several default converters from the configuration values which are typed as Strings (e.g. int, Integer, Double, float, …​). However, you can also use your custom types as a configuration values. This can be done by implementing org.eclipse.microprofile.config.spi.Converter<T> and adding its fully qualified class name in the META-INF/services/org.eclipse.microprofile.config.spi.Converter file. Let’s create a new class org.wildfly.quickstarts.microprofile.config.converter.type.MicroProfileCustomValue:

package org.wildfly.quickstarts.microprofile.config.converter.type;

public class MicroProfileCustomValue {

    private String name;

    public MicroProfileCustomValue(String name) {
        this.name = name;
    }

    public String getName() {
        return name;
    }
}

which represents our custom value and the corresponding Converter<MicroProfileCustomValue> implementation org.wildfly.quickstarts.microprofile.config.converter.MicroProfileCustomValueConverter:

package org.wildfly.quickstarts.microprofile.config.converter;

import org.eclipse.microprofile.config.spi.Converter;
import org.wildfly.quickstarts.microprofile.config.converter.type.MicroProfileCustomValue;

public class MicroProfileCustomValueConverter implements Converter<MicroProfileCustomValue> {

    @Override
    public MicroProfileCustomValue convert(String value) {
        return new MicroProfileCustomValue(value);
    }
}
Note
 Please note that your custom converter class must be public and must have a public no-argument constructor. It also must not be abstract.

Then you need to include the fully qualified class name of the converter in a service file src/main/resources/META-INF/services/org.eclipse.microprofile.config.spi.Converter:

org.wildfly.quickstarts.microprofile.config.converter.MicroProfileCustomValueConverter

After this is done you can use your custom type as a configuration value. Create a new resource class org.wildfly.quickstarts.microprofile.config.ConverterResource:

package org.wildfly.quickstarts.microprofile.config;

import org.eclipse.microprofile.config.inject.ConfigProperty;
import org.wildfly.quickstarts.microprofile.config.converter.type.MicroProfileCustomValue;

import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;

@Path("/converter")
public class ConverterResource {

    @Inject
    @ConfigProperty(name = "custom.converter.prop")
    private MicroProfileCustomValue microProfileCustomValue;

    @GET
    @Path("/value")
    public String customConverterProp() {
        return microProfileCustomValue.getName();
    }
}

And define the custom.converter.prop in, for instance, microprofile-config.properties file.

custom.converter.prop=MyCustomConverterValue

Build and redeploy the application

$ mvn clean package wildfly:deploy

And now you can access the http://localhost:8080/microprofile-config/converter/value endpoint using your browser or curl http://localhost:8080/microprofile-config/converter/value to make use of the custom converter. You will see the configured value which is taken from our created MicroProfileCustomValue object.

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-maven-plugin</artifactId>
                      <configuration>
                          <discover-provisioning-info>
                              <version>${version.server}</version>
                          </discover-provisioning-info>
                          <bootable-jar>true</bootable-jar>
                          <!--
                            Rename the output war to ROOT.war before adding it to the server, so that the
                            application is deployed in the root web context.
                          -->
                          <name>ROOT.war</name>
                          <add-ons>...</add-ons>
                      </configuration>
                      <executions>
                          <execution>
                              <goals>
                                  <goal>package</goal>
                              </goals>
                          </execution>
                      </executions>
                  </plugin>
                  ...
              </plugins>
          </build>
      </profile>

The plugin uses WildFly Glow to discover the feature packs and layers required to run the application, and provisions a server containing those layers.

If you get an error or the server is missing some functionality which cannot be auto-discovered, you can download the WildFly Glow CLI and run the following command to see more information about what add-ons are available:

wildfly-glow show-add-ons
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-config-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-config 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:start-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: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>
                            <discover-provisioning-info>
                                <version>${version.server}</version>
                                <context>cloud</context>
                            </discover-provisioning-info>
                            <!--
                                The parent POM's 'openshift' profile renames the output archive to ROOT.war so that the
                                application is deployed in the root web context. Add ROOT.war to the server.
                            -->
                            <filename>ROOT.war</filename>
                            <add-ons>...</add-ons>
                        </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 context which enables a configuration tuned for OpenShift environment.

The plugin uses WildFly Glow to discover the feature packs and layers required to run the application, and provisions a server containing those layers.

If you get an error or the server is missing some functionality which cannot be auto-discovered, you can download the WildFly Glow CLI and run the following command to see more information about what add-ons are available:

wildfly-glow show-add-ons

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-config -f charts/helm.yaml wildfly/wildfly --wait --timeout=10m0s 
NAME: microprofile-config
...
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-config

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: main
  contextDir: microprofile-config
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-config -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-config path segment after HOST:PORT.

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.

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-config --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-config

Building and running the quickstart application with Kubernetes

Build the WildFly Quickstart to Kubernetes with Helm Charts

For Kubernetes, the build with Apache Maven uses an openshift Maven profile to provision a WildFly server, suitable for running on Kubernetes.

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>
                            <discover-provisioning-info>
                                <version>${version.server}</version>
                                <context>cloud</context>
                            </discover-provisioning-info>
                            <!--
                                The parent POM's 'openshift' profile renames the output archive to ROOT.war so that the
                                application is deployed in the root web context. Add ROOT.war to the server.
                            -->
                            <filename>ROOT.war</filename>
                            <add-ons>...</add-ons>
                        </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 context which enables a configuration tuned for Kubernetes environment.

The plugin uses WildFly Glow to discover the feature packs and layers required to run the application, and provisions a server containing those layers.

If you get an error or the server is missing some functionality which cannot be auto-discovered, you can download the WildFly Glow CLI and run the following command to see more information about what add-ons are available:

wildfly-glow show-add-ons

Getting Started with Kubernetes and Helm Charts

This section contains the basic instructions to build and deploy this quickstart to Kubernetes using Helm Charts.

Install Kubernetes

In this example we are using Minikube as our Kubernetes provider. See the Minikube Getting Started guide for how to install it. After installing it, we start it with 4GB of memory.

minikube start --memory='4gb'

The above command should work if you have Docker installed on your machine. If, you are using Podman instead of Docker, you will also need to pass in --driver=podman, as covered in the Minikube documentation.

Once Minikube has started, we need to enable its registry since that is where we will push the image needed to deploy the quickstart, and where we will tell the Helm charts to download it from.

minikube addons enable registry

In order to be able to push images to the registry we need to make it accessible from outside Kubernetes. How we do this depends on your operating system. All the below examples will expose it at localhost:5000

# On Mac:
docker run --rm -it --network=host alpine ash -c "apk add socat && socat TCP-LISTEN:5000,reuseaddr,fork TCP:$(minikube ip):5000"

# On Linux:
kubectl port-forward --namespace kube-system service/registry 5000:80 &

# On Windows:
kubectl port-forward --namespace kube-system service/registry 5000:80
docker run --rm -it --network=host alpine ash -c "apk add socat && socat TCP-LISTEN:5000,reuseaddr,fork TCP:host.docker.internal:5000"

Prerequisites

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

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 Kubernetes with Helm Charts

The backend will be built and deployed on Kubernetes with a Helm Chart for WildFly.

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

mvn -Popenshift package wildfly:image

This will use the openshift Maven profile we saw earlier to build the application, and create a Docker image containing the WildFly server with the application deployed. The name of the image will be microprofile-config.

Next we need to tag the image and make it available to Kubernetes. You can push it to a registry like quay.io. In this case we tag as localhost:5000/microprofile-config:latest and push it to the internal registry in our Kubernetes instance:

# Tag the image
docker tag microprofile-config localhost:5000/microprofile-config:latest
# Push the image to the registry
docker push localhost:5000/microprofile-config:latest

In the below call to helm install which deploys our application to Kubernetes, we are passing in some extra arguments to tweak the Helm build:

  • --set build.enabled=false - This turns off the s2i build for the Helm chart since Kubernetes, unlike OpenShift, does not have s2i. Instead, we are providing the image to use.

  • --set deploy.route.enabled=false - This disables route creation normally performed by the Helm chart. On Kubernetes we will use port-forwards instead to access our application, since routes are an OpenShift specific concept and thus not available on Kubernetes.

  • --set image.name="localhost:5000/microprofile-config" - This tells the Helm chart to use the image we built, tagged and pushed to Kubernetes' internal registry above.

$ helm install microprofile-config -f charts/helm.yaml wildfly/wildfly --wait --timeout=10m0s --set build.enabled=false --set deploy.route.enabled=false --set image.name="localhost:5000/microprofile-config"
NAME: microprofile-config
...
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:

kubectl get deployment microprofile-config

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: main
  contextDir: microprofile-config
deploy:
  replicas: 1

This will create a new deployment on Kubernetes 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

To be able to connect to our application running in Kubernetes from outside, we need to set up a port-forward to the microprofile-config service created for us by the Helm chart.

This service will run on port 8080, and we set up the port forward to also run on port 8080:

kubectl port-forward service/microprofile-config 8080:8080

The server can now be accessed via http://localhost:8080 from outside Kubernetes. Note that the command to create the port-forward will not return, so it is easiest to run this in a separate terminal.

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-config path segment after HOST:PORT.

Run the Integration Tests with Kubernetes

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

Note

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

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=http://localhost:8080

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

$ helm uninstall microprofile-config

To stop the port forward you created earlier use:

$ kubectl port-forward service/microprofile-config 8080:8080

Conclusion

MicroProfile Config provides a way for your application to separate the configuration from your application code which is a requirement for modern applications targeting containers and cloud deployments. It allows you to adjust every aspect of the configuration according to the application needs. The more information can be found in the MicroProfile config specification.