Contents
- What you'll learn
- Background concepts
- Example: DevOps pipeline
- Enabling MicroProfile Config in Open Liberty
- Injecting configuration through @ConfigProperty annotation
- Providing optional default values
- Configuring with the properties file
- Configuring with an environment variable
- Configuring with a system property
- Configuring as a variable element in server.xml
- Configuring as an appProperties element scoped by application
- Changing the ordinal of a ConfigSource
- Default ConfigSources playground
- Nice work! Where to next?
Tags
Separating configuration from code in microservices
Learn how to perform static configuration injection using MicroProfile Config.
What you'll learn
Explore how to inject configuration data into a microservice without repackaging the application each time the underlying runtime environment changes. MicroProfile makes building configurable microservices easy with its MicroProfile Config feature. Application configuration properties from multiple sources are combined into a single set of configuration properties and accessed from a single API by your application.
Using the MicroProfile Config API, the sample application illustrates how a configuration property can be assigned a value in multiple configuration sources. Each source is assigned a priority. The value from the source with the highest priority takes precedence over that from a lower priority. This method allows code to run unchanged under different configurations for prototyping, development, test, quality assurance, staging, and production environments since an existing configuration value can easily be overridden as the need arises.
When you arrive at the section about the Default ConfigSources playground, you can create your own properties and update the configuration sources with values or change the source's priority. A chart will show you which value the property is assigned.
Background concepts
MicroProfile Config uses Contexts and Dependency Injection (CDI) to inject configuration property values directly into an application without requiring user code to retrieve them. The injected values are defined as static because they are set only at application startup.
The API combines configuration values from multiple sources, each known as a ConfigSource. Each ConfigSource has a specified priority, defined by its ordinal value. A higher ordinal means that the values taken from this ConfigSource will override values from ConfigSources with a lower ordinal value.
MicroProfile Config has 5 default ConfigSources:
- All
META-INF/microprofile-config.properties
found on the class path (default ordinal = 100). - Environment variables (default ordinal = 300).
- System properties (default ordinal = 400).
- Defined as a
variable
element in the Libertyserver.xml
file (default ordinal = 500). - Defined as an
appProperties property
element in the Libertyserver.xml
file (default ordinal = 600).
An optional default value can be specified using Java annotations. The optional default value applies if the application does not find configuration values in any of the ConfigSources. The priority of each ConfigSource and the optional default value is shown in the following diagram:
Example: DevOps pipeline
Imagine that you're developing and deploying a DisplayCarTypes microservice so that you can display the types of cars that are currently available for purchase from your business. This microservice has a dependency on another microservice called ObtainCarTypes, which provides the currently available list. As you develop your DisplayCarTypes microservice, you need to ensure that it works correctly when it interacts with the ObtainCarTypes microservice. For stability and security reasons, you don't want to test against the production version of ObtainCarTypes during the development pipeline. Instead, you run six instances of the ObtainCarTypes microservice, one for each stage of the devOps pipeline as shown in the following diagram:
As you progress through this guide, you will set a configuration property for the port value to specify which of the six ObtainCarTypes instances the DisplayCarTypes microservice should connect to.
Enabling MicroProfile Config in Open Liberty
Begin by enabling the MicroProfile Config 1.3 feature in the server.xml
file of the Open Liberty server. This feature allows you to use the MicroProfile Config API to externalize configuration data.
featureManager
element that is in the server.xml
file.Alternatively, click
Then, click
Injecting configuration through @ConfigProperty annotation
After you modify your server.xml
file to include the mpConfig feature, inject a single configuration property value directly into your code with the @Inject
and the @ConfigProperty
annotations. The injected value is static and does not change after the application starts.
You can specify a value in the runtime environment for mandatory configuration properties. Properties are mandatory when the annotation does not specify an optional default value. When the mandatory configuration property value is not found in any of the ConfigSources, a NoSuchElementException
is thrown during application startup.
port
configuration property into the code, add the following @Inject
and @ConfigProperty
annotations to line 9 before declaring the private int port
.Alternatively, click
Then, click
Providing optional default values
You can specify a default value for a configuration property using the defaultValue parameter in the @ConfigProperty
annotation. This value is used when a value is not specified in any MicroProfile Config configuration source.
@ConfigProperty
annotation on line 9 to the following code.Alternatively, click
Then, click
A
, B
, C
and D
.Configuring with the properties file
You can provide the /META-INF/microprofile-config.properties
file as part of your packaged application. The /META-INF/microprofile-config.properties
file may be created in multiple locations, but you must specify these file locations in your class path. Do not specify the same configuration property in multiple /META-INF/microprofile-config.properties
files that have the same ordinal value, or the application returns an indeterminate property value.
The properties file contains settings with a default ordinal of 100, which overrides the injected default values with the same key so the port
property value in the microprofile-config.properties
file is used.
/META-INF/microprofile-config.properties
, add the following on line 1.Alternatively, click
Then, click
/META-INF/microprofile-config.properties
file is used. The development port (9081) of the ObtainCarTypes microservice returns the values carA
and carB
.Configuring with an environment variable
In Open Liberty, you can use server.env
files at the installation and server levels to specify environment variables. The installation level file is located at ${wlp.install.dir}/etc/server.env
, and the server level file is located at ${server.config.dir}/server.env
. If both files exist, the contents of the two files are merged. If the same environment variable is in both files, the value in the server level file takes precedence over the value in the installation level file.
Environment variables can also be set using the command line.
Some operating systems impose character restrictions on the name of an environment variable. For example, Linux environments do not support full stops (.
) in environment variable names so you can not have property names like user.name
in server.env
. To set a value for a config property that has a name containing disallowed characters from an environment variable, this configsource maps config property names to environment variable names using the following rules and the first match is returned:
- An exact match
- An environment variable name in which all characters that are not alphanumeric or the underscore (
_
) character are replaced with an underscore character (eguser_name
) - An environment variable name in which all characters that are not alphanumeric or the underscore (
_
) character are replaced with an underscore character and the name is converted to upper case (egUSER_NAME
).
Use the ${server.config.dir}/server.env
file to configure the port
environment variable. The server.env
file contains the environment settings with a default ordinal value of 300 which is higher than the default ordinal value of 100 for the /META-INF/microprofile-config.properties
file. Thus, the port
property value in server.env
is used.
server.env
, add the following on line 1.Alternatively, click
Then, click
typeA
, typeB
, and typeC
.Configuring with a system property
Configuration variables can be retrieved from the Java system properties, which have a default ordinal of 400. Open Liberty adds properties from the server’s bootstrap.properties
and jvm.options
files to the Java system properties. You can create and configure the jvm.options
file in multiple locations within your Open Liberty installation directory.
The following list shows the different locations where Open Liberty checks for jvm.options
files:
${wlp.install.dir}/usr/shared/jvm.options
${server.config.dir}/configDropins/defaults/jvm.options
${server.config.dir}/jvm.options
${server.config.dir}/configDropins/overrides/jvm.options
The contents of these files are merged. The latter files take precedence in the case of duplicate properties. If none of these files are present, then the ${wlp.install.dir}/etc/jvm.options
file is used. If a property exists in both bootstrap.properties
and jvm.options
, then the value from jvm.options
takes precedence.
In this example, use the ${server.config.dir}/bootstrap.properties
file to configure the port
system property.
bootstrap.properties
.Alternatively, click
Then, click
bootstrap.properties
file is used. The quality assurance port (9083) of the ObtainCarTypes microservice returns values SUV
, Crossover
, Coupe
, and Truck
.Configuring as a variable element in server.xml
With the Open Liberty implementation of MicroProfile Config 1.3 you can define configuration values as a variable in the Liberty server's server.xml
configuration file. Including a variable
element in the server.xml
file assigns a value to the configuration entity that may be accessed by any application running on the server.
Properties declared as variable
elements in the Liberty server.xml
file have an ordinal value of 500. They override configuration values from ConfigSources with lower ordinal values. If duplicate properties exist in the server.xml
file, the last value specified is used by MicroProfile Config.
variable
element on line 10 of the server.xml
file.Alternatively, click
Then, click
variable
element in the server.xml
file is used. The staging port (9084) of the ObtainCarTypes microservice returns values SUV
, Crossover
, Coupe
, Truck
, and Convertible
.Configuring as an appProperties element scoped by application
You can also define a configuration value as an appProperties
property
element in the Liberty server's server.xml
configuration file. This assigns a value to the configuration property that may be accessed by the specified application. The appProperties
element can be specified in either an application
or a webApplication
element.
Properties defined in appProperties
elements in the Liberty server.xml
file have an ordinal value of 600. If duplicate property
elements exist, the last value specified will be used by MicroProfile Config.
appProperties
property
element on line 13 of the server.xml
file.Alternatively, click
Then, click
appProperties
property
element in the server.xml
file is used. The production port (9085) of the ObtainCarTypes microservice returns values SUV
, Crossover
, Coupe
, Truck
, Convertible
, and Van
.Changing the ordinal of a ConfigSource
You can override the default ordinal value of a ConfigSource by adding the config_ordinal
property to your configuration source file. The configuration source with the highest ordinal value takes precedence.
When updating the default config ordinal value in the server.xml config source, the value is added just like any other variable
or appProperties
element. For example, <variable name="config_ordinal" value="875" />
. Otherwise, in the other ConfigSources, set config_ordinal
as a property.
Adding config_ordinal
to /META-INF/microprofile-config.properties
with a value of 700 increases its ordinal value. The port value from /META-INF/microprofile-config.properties
now overrides the port value from the appProperties
property
element in the Liberty server.xml
file, which has a default ordinal of 600.
/META-INF/microprofile-config.properties
file, add the following on line 2.Alternatively, click
Then, click
/META-INF/microprofile-config.properties
file is used instead of the one defined in the server.xml
file as an appProperties
property
element. The Development port (9081) of the ObtainCarTypes microservice returns the values carA and carB.Default ConfigSources playground
Now that you've learned the various ways of defining configuration properties, you can see how they all work together.
To review, here are the six places to inject properties:
- Java annotations
@Inject @ConfigProperty
withdefaultValue
inInventoryConfig.java
(no ordinal) - Properties file through
/META-INF/microprofile-config.properties
(default ordinal = 100) - Environment variables through
server.env
(default ordinal = 300) - System properties through
bootstrap.properties
(default ordinal = 400) - As a
variable
element in theserver.xml
file (ordinal = 500) - As a
appProperties
property
element in theserver.xml
file (ordinal = 600)
You can add new properties and override the default ordinal value of the ConfigSource files.
@Inject @ConfigProperty (name="propertyName");
to include the new properties in the InventoryConfig.java
file. Use propertyName=propertyValue
to add the new properties to any of the properties files or the server.env
file. Use XML syntax to add the new properties to the server.xml
file. Add the
config_ordinal
property to override the default ordinal value in any of the ConfigSources. Click Run to see the file ordinal priority and the property values being used.
Nice work! Where to next?
Nice work! You learned how to use MicroProfile Config to separate configuration from code by using injection and how to provide configuration values with properties files, environment variables, system properties, and the Liberty server.xml file. You also learned the default ordinals for each of these configuration sources and how to override them.
What did you think of this guide?




Thank you for your feedback!
What could make this guide better?
Raise an issue to share feedback
Create a pull request to contribute to this guide
Need help?
Ask a question on Stack Overflow
Like Open Liberty? Star our repo on GitHub.
StarWhere to next?
Download the sample application for this guide bundled with Open Liberty on github
Keep exploring MicroProfile with these guides.
Learn more about MicroProfile.