Jan Meznarič edited this page May 8, 2018 · 9 revisions

Configuration management with KumuluzEE

This article presents motivation for using configuration management frameworks when developing microservices for cloud-native architectures, introduces configuration management in KumuluzEE and presents basic concepts and steps needed to enrich KumuluzEE applications with provided configuration managements concepts.

Configuration management for microservices

Effective configuration management is important especially when designing microservices for cloud-native architectures. Ideally, developer is provided with options to inject configuration properties directly into the application code, with values dynamically loaded from a pool of provided configuration sources, such as environment variables, property files, internal storage, etc. Main advantages of this design pattern are:

  • separation of configuration properties and application code,
  • support for pluggable configuration sources with unified interface,
  • monitoring changes in configuration sources and dynamic reconfiguration without the need for redeploying applications.


KumuluzEE microservices framework provides basic support for injecting configuration properties into microservices. It includes annotations for injecting configuration properties, which are dynamically loaded from basic configuration sources. Environment variables, YAML configuration files and java properties files are supported. Extensions for other external dedicated configuration sources such as etcd and Consul use the same interfaces and can be included as a KumuluzEE Config extension.

Annotations, interfaces and implementation for basic configuration sources are part of cdi KumuluzEE module.

Getting started

Basic concepts for managing configuration with KumuluzEE are configuration parameter keys, configuration sources, ConfigurationUtil class and properly annotated properties bean. When developing microservices with KumuluzEE we first have to structure our configuration properties keys and define configuration sources with configuration values, then we can access defined configuration with ConfigurationUtil class or create a properties bean and extend it with appropriate configuration annotations. All those steps are explained in more detail in the following sections.

Configuration parameter keys

Configuration parameters are stored in the key-value format (e.g. port=8080). For better transparency, configuration keys are organised into a tree structure. Example configuration structure:

- kumuluzee
  - name
  - env
    - name
  - version
  - server
    - base-url
    - http
      - port

Configuration parameter key names reflect the tree structure of the configuration. In key names, individual layers of the tree structure are separated with dots. Example key from the configuration above is Key names are written in spinal-case format, e.g. kumuluzee.server.base-url.

Configuration values can be stored in form of arrays. A configuration parameter key that represents an array ends with an array item index enclosed in square bracket, e.g. kumuluzee.array[1].key.

Configuration sources

Configuration properties can be stored in different configuration sources. Value can be a primitive, an object or an array. Configuration is loaded from all available sources according to the priorities that are set with an ordinal number. If a key is not defined in a source with the highest priority, it is looked-up in the source with lower priority (and so on). All supported source formats are described further in this section. Sources are listed in order of priority, where the first source has the highest priority.

System properties

Configuration properties defined as system properties have the highest priority with an ordinal number 400. Configuration keys have to be written in standard format, e.g. kumuluzee.server.base-url.

Environment variables

Configuration properties defined as environment variables have the second highest priority with an ordinal number 300. Configuration keys have to be written in standard format for environment variables, i.e. with capital case letters and tree levels separated with underscores. Hyphens and square brackets in key names can be omitted. Configuration framework will first look for a key without hyphens, e.g.:


If a key in this format does not exist, it will then try to look for a key with hyphens and square brackets, e.g.:


Configuration files

Framework supports configuration files in YAML and Java properties formats. Configuration files have an ordinal number 100. Framework loads one configuration file that is present in the classpath, trying to load them in the following order:

  • config.yml
  • config.yaml

File name can be overwritten with a system property


Configuration in YAML format is loaded from file config.yml or config.yaml (file name can be overwritten with a system property stored in resources folder. File structure mirrors the tree structure of configuration keys. Example file:

  name: customer-service
    name: dev
  version: 1.0.0
    base-url: http://localhost:8081
      port: 8081

Java properties

If a YAML file is not present, configuration is loaded from file (file name can be overwritten with a system property stored in resources folder. Example file:

Configuration properties defined in Java properties file have the lowest priority.

Accessing configuration

There are two ways of accessing configuration: manually, using methods from ConfigurationUtil class, or by using a properties bean that automatically loads configuration. Both methods are described in this section.

ConfigurationUtil class

ConfigurationUtil class can be used for retrieving values of configuration parameters from the configuration framework. It is implemented as a singleton that is retrieved with the getInstance() method. Configuration values can be retrieved with the following methods, depending on their type:

  • Optional get(String key)
  • Optional getBoolean(String key)
  • Optional getInteger(String key)
  • Optional getLong(String key)
  • Optional getDouble(String key)
  • Optional getFloat(String key)

Example call:

Integer port = ConfigurationUtil.getInstance().getInteger("kumuluzee.server.http.port");

Properties bean

A CDI bean can be used for retrieving and storing configuration values during application lifecycle. Configuration can be injected into any application scoped bean. A pattern with one dedicated properties bean for storing and accessing configuration is encouraged. Configuration properties can be stored in fields of primitive types (String, Boolean, Integer, Long, Float and Double), or in a custom nested classes. All fields shall have publicly available getter and setter methods.

An example properties bean that can be used to access configuration properties:

public class ConfigPropertiesExample {
    private String name;
    private String env;
    private Server server;
    // getter and setter methods


To enable automatic configuration injection, we have to annotate our properties bean with @ConfigBundle annotation.

Annotation @ConfigBundle takes one parameter that represents the first part of the key, typically a prefix that is the same for all keys defined in the bean. If value is not provided, it is set to bean name in spinal-case format (e.g. config-properties-example). To access configuration values at root level, set the value to ".".

Second part of the key is taken from the field name. Field name in example bellow maps to key This behavior can be overwritten with annotation @ConfigValue by specifying second part of the key with parameter value, which overrides field name used to form a configuration key (e.g.

At bean initialisation, all fields with publicly available setters will be initialised from configuration sources according to specified key names.

An example properties bean that with configuration annotations:

public class ConfigPropertiesExample {
    private String name;
    private String env;
    private Server server;
    // getter and setter methods

public class Server {
    private String baseUrl;
    private Integer port;
    // getter and setter methods

This bean can then be injected and used anywhere in application to access injected configuration properties. Example:

private ConfigPropertiesExample configProperties;

String url = configProperties.getServer().getBaseUrl();


In this article we presented an importance of configuration management and showed basic steps for implementing efficient configuration management with KumuluzEE framework. Additional configuration sources such as etcd and Consul with corresponding documentation and tutorials can be found in extension KumuluzEE Config. There are also a few samples, basic configuraiton sample and samples for etcd and Consul extensions.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.