Skip to content
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Go to file
Cannot retrieve contributors at this time

KumuluzEE Config

Build Status

Configuration extension for the KumuluzEE microservice framework with support for etcd and Consul configuration servers.

KumuluzEE Config is an open-source configuration management project for the KumuluzEE framework. It extends basic configuration framework which is a part of KumuluzEE framework, described here. It provides support for additional configuration sources in addition to environment variables, system properties and configuration files.

KumuluzEE Config follows the idea of a unified configuration API for the framework and provides additional configuration sources which can be utilised with a standard KumuluzEE configuration interface.

KumuluzEE Config has been designed to support modularity with pluggable configuration sources. Currently, etcd and Consul key-value stores are supported to act as configuration servers. In the future, other data stores and configuration servers will be supported too (contributions are welcome).

Project supports KumuluzEE version 2.4.0 or higher.


KumuluzEE defines interfaces for common configuration management features and three basic configuration sources; environment variables, system properties and configuration files. To include configuration sources from this project you need to include a dependency to an implementation library.

You can include etcd implementation by adding the following dependency:


Currently, only API v2 is supported. Future releases will support API v3 in a form of a new KumuluzEE Config module.

You can include Consul implementation by adding the following dependency:


Note that currently, only one configuration server implementation (etcd or Consul) can be added to a single project. Adding both of them may result in unexpected behaviour.

Configuring etcd

To connect to an etcd cluster, an odd number of etcd hosts must be specified with configuration key kumuluzee.config .etcd.hosts in format ',,'.

Etcd can be configured to support user authentication and client-to-server transport security with HTTPS. To access authentication-enabled etcd host, username and password have to be defined with configuration keys kumuluzee.config.etcd.username and kumuluzee.config.etcd.password. To enable transport security, follow To access HTTPS-enabled etcd host, PEM certificate string have to be defined with configuration key

Sample configuration file:

    start-retry-delay-ms: 500
    max-retry-delay-ms: 900000
      username: root
      password: admin
      ca: -----BEGIN CERTIFICATE-----
          -----END CERTIFICATE-----

Configuring Consul

By default, KumuluzEE Config Consul automatically connects to the local agent at http://localhost:8500. This behaviour can be overridden by specifying agent URL with configuration key kumuluzee.config.consul.agent.

Configuration source priorities

Included source acts as any other configuration source. It has the third highest priority, which means that properties from etcd override properties from configuration files and can be overwritten with properties from environmental variables and system properties.

Configuration properties inside etcd

Configuration properties are stored in etcd key/value store.

Key names are automatically parsed from KumuluzEE to etcd format (e.g. -> environments/dev/name).

Configuration properties are in etcd stored in a dedicated namespace, which is automatically generated from configuration keys, and kumuluzee.version. Example: dev, customer-service, kumuluzee.version: 1.2.3 is mapped to namespace environments/dev/services/customer-service/1.2.3/config. If or kumuluzee.version keys are not specified, defaults are used (dev and 1.0.0). If is not specified, namespace environments/<environment>/services/config is used. Automatic namespace generation can be overwritten with key kumuluzee.config.namespace. Example: kumuluzee.config.namespace: environments/dev/services/config.

Namespace is used as a first part of the key used for etcd key/value store. Example: with set dev, field port from example bellow is in etcd stored in key /environments/dev/services/test-service/config/port.

Lists can be stored in etcd in dedicated directories with key names as indexes [0], [1], [2], ...

The following list in yaml

   - first
   - second
   - third 

can be stored with the following etcd keys:


Configuration properties inside Consul

Configuration properties in Consul are stored in a similar way as in etcd.

Since Consul uses the same format as etcd, key names are parsed in similar fashion.

KumuluzEE Config Consul also stores keys in automatically generated dedicated namespaces.

For more details, see section above.

Retrieving configuration properties

Configuration can be retrieved the same way as in basic configuration framework.

Configuration properties can be accessed with ConfigurationUtil class. Example:

String keyValue = ConfigurationUtil.getInstance().get("key-name");

Configuration properties can be injected into a CDI bean with annotations @ConfigBundle and @ConfigValue. Example:

public class ConfigPropertiesExample {
    private Boolean servicePort;
    // getter and setter methods


Since configuration properties in etcd and Consul can be updated during microservice runtime, they have to be dynamically updated inside the running microservices. This behaviour can be enabled with watches.

Watches can be enabled with annotation parameter @ConfigValue(watch = true) or by subscribing to key changes.

If watch is enabled on a field, its value will be dynamically updated on any change in configuration source, as long as new value is of a proper type. For example, if value in configuration store, linked to an integer field, is changed to a non-integer value, field value will not be updated. Example of enabling watch with annotation:

public class ConfigPropertiesExample {
    @ConfigValue(watch = true)
    private Boolean servicePort;
    // getter and setter methods

Subscribing to key changes is done with an instance of ConfigurationUtil class. Example:

String watchedKey = "maintenance";

ConfigurationUtil.getInstance().subscribe(watchedKey, (String key, String value) -> {

    if (watchedKey.equals(key)) {

        if ("true".equals(value.toLowerCase())) {
  "Maintenence mode enabled.");
        } else {
  "Maintenence mode disabled.");



If the key is not present in configuration server, a value from other configuration sources is returned. Similarly, if the key is deleted from configuration server, a value from other configuration sources is returned.

Retry delays

Etcd and Consul implementations support retry delays on watch connection errors. Since they use increasing exponential delay, two parameters need to be specified:

  • kumuluzee.config.start-retry-delay-ms, which sets the retry delay duration in ms on first error - default: 500
  • kumuluzee.config.max-retry-delay-ms, which sets the maximum delay duration in ms on consecutive errors - default: 900000 (15 min)

Build the microservice

Ensure you have JDK 8 (or newer), Maven 3.2.1 (or newer) and Git installed.

Build the config library with command:

    mvn install

Build archives are located in the modules respected folder target and local repository .m2.

Run the microservice

Use the following command to run the sample from Windows CMD:

java -cp target/classes;target/dependency/* 


Recent changes can be viewed on Github on the Releases Page


See the contributing docs

When submitting an issue, please follow the guidelines.

When submitting a bugfix, write a test that exposes the bug and fails before applying your fix. Submit the test alongside the fix.

When submitting a new feature, add tests that cover the feature.