External configuration of microservices

Microservices are deployed in multiple environments. Externalizing the configuration with MicroProfile Config helps microservices to run in different environments without code changes.

During their lifecycle, microservices are deployed repeatedly across development, test, and production environments. Each environment requires different configuration data. For example, backing services might require changes in connection details for databases, messaging services, and API accessible consumer services. Your application needs to be able to swap between local and external services without needing you to rewrite the code.

Similarly, in the cloud, microservices that are deployed to Kubernetes clusters must communicate, for example, through HTTP calls. Therefore, port binding, or knowing which port to connect to, is important. As instances of microservices are created and destroyed to scale the application up and down in Kubernetes, port numbers can change. You need to assign new port numbers to the microservices and inject information during startup without changing the code. For more information, see Configuring microservices running in Kubernetes.

Separate configuration from code with MicroProfile Config

MicroProfile Config is an API that helps to separate configuration from application code, so that the same application code works in different environments. With MicroProfile Config, you can inject the external configuration into a service that is running in a container without repackaging it. You can use MicroProfile Config with Open Liberty by enabling the MicroProfile Config feature or the MicroProfile feature in your server.xml file. The MicroProfile feature is a convenience feature that enables all the core MicroProfile features for Open Liberty.

Applications can use MicroProfile Config as a single API to retrieve configuration information from different sources such as system properties, system environment variables, properties files, XML files, or data sources. In MicroProfile Config, these data sources are called configuration sources. Configuration properties are the properties on the Contexts and Dependency Injection (CDI) beans in your application. MicroProfile Config uses CDI to inject configuration property values directly into an application without the need for application code to retrieve them. The same configuration property can be defined in multiple configuration sources.

With MicroProfile Config, you can inject an individual property into a class, or inject multiple properties in one CDI bean. You can also retrieve values from configuration without using a CDI bean.

MicroProfile Config can configure other MicroProfile capabilities. It externalizes the configuration of keystores when microservices are secured. For example, in MicroProfile JSON Web Token, the public key location and verification can be set in properties files. If the location of the key repository changes, you can easily update the information. MicroProfile Config is also used in the configuration of channel attributes. In MicroProfile Reactive Messaging, it can set the connection details of messaging channels, connectors, and the topic names that the application uses to produce messages. Additionally, MicroProfile Config helps override values in fault tolerance. In MicroProfile Fault Tolerance, it can set the value of an annotation so that you can change the value if the tolerance is too low or too high.

For more information, see MicroProfile Config properties.

Default configuration sources

In Open Liberty, MicroProfile Config has six default configuration sources. Each configuration source has a specified priority, which is defined by its ordinal value. A higher ordinal means that the values that are taken from this configuration source override configuration sources with a lower ordinal value.

The following table shows the MicroProfile Config configuration sources in Open Liberty, their default ordinal values, and an example to each of the configuration sources.

Default MicroProfile Config configuration sources in Open Liberty
Configuration SourceDefault ordinal valuesExample Configuration FileExample Values

Values that are defined as a property element in the appProperties element in either an application or webApplication element in the Open Liberty server.xml file.

600

server.xml

<appProperties>
    <property name="server.port" value="9080"/>
</appProperties>

Values that are defined in a variable element in the Open Liberty server.xml file.

500

server.xml

<variable name="server.port" value="9080"/>

System properties

400

jvm.options

-Dserver.port=9080

Environment variables

300

server.env

server_port=9080

All META-INF/microprofile-config.properties files that are found on the class path

100

microprofile-config.properties

server.port=9080

Values that are defined as a defaultValue in a variable element in the Open Liberty server.xml file.

1

server.xml

<variable name="server.port" defaultValue="9080"/>

You can specify an optional default value by using Java annotations. The optional default value applies if the application does not find the configuration values in any of the configuration sources. You can prioritize which configuration source to use for a property value by setting the ordinal value for that configuration source. For more information, see Changing the ordinal of a ConfigSource.