content/documentation/extensions/mod_consul.adoc

:jbake-type: page
:jbake-status: published

= Apache Tamaya - Extension: Integration with Consul (Hashicorp)

toc::[]


[[Consul]]
== Integration with consul (Extension Module)

Tamaya _Consul_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.

=== What functionality this module provides ?

Tamaya _Consul_ provides different artifacts which allows use of
link:http://www.consul.io[Consul from Hashicorp] as configuration backend. Basically the
module supports read-only integration (as a +ConsulPropertySource+ as well
as a writing configuration changes back (based on Tamaya's +MutableConfiguration+ API
defined by the link:mod_mutable_config.html[tamaya-mutable-config] extension module.


=== Compatibility

The module is based on Java 8.


=== Installation

To use _tamaya-consul_ you only must add the corresponding dependency to your module:

[source, xml, subs=attributes+]
-----------------------------------------------
<dependency>
  <groupId>org.apache.tamaya.ext</groupId>
  <artifactId>tamaya-consul</artifactId>
  <version>{tamaya_version}</version>
</dependency>
-----------------------------------------------


=== The Functionality Provided

Tamaya Consul provides two artifacts:

* The +org.apache.tamaya.consul.ConsulPropertySource+ is a +PropertySource+ with a default
  ordinal of 100 and the name 'consul'.
* +org.apache.tamaya.consul.ConsulPropertySource+ is based on +org.apache.tamaya.consul.AbstractConsulPropertySource+,
  which provides all required basic functionality to implement your own consul based property
  sources.

Access of consul key/value pairs is through the normal Tamaya API.


=== The ConsulPropertySource

The +ConsulPropertySource+ allows the consul servers to be used as configuration backends. It provides:

* a Consul based property source implementation.
* configurable caching of key/values accessed (Consul does not provide reading all values out).
* configuring a optional key prefix for defining a namespace for Tamaya configuration within the consul key/value
  store.
* +ConsulPropertySource+ reads the +tamaya.consul.urls+ system and environment property to evaluate the consul servers
  to be used (comma separated). The API just performs a Round-Robin through the list of
  configured servers. Without any configuration +http://127.0.0.1:2400+ is used. If no connection to any consul
  server can be established a warning will be logged, but deployment will not fail.
* The +ConsulPropertySource+ finally also allows the values read from the consul cluster to be mapped with a prefix.
  This allows to let all values stored in consul have their own namespace. E.g. the Tamaya key `a.b` is mapped
  to `foo.a.b`, when the prefix is set to `foo.`. The prefix can be activated by setting the
  `tamaya.consul.prefix` system or environment property.


=== The AbstractConsulPropertySource

The +AbstractConsulPropertySource+ provides all features from +ConsulPropertySource+ but does not define how the
property source is exactly configured, so you have full control.