content/documentation/extensions/mod_etcd.adoc

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

= Apache Tamaya - Extension: Integration with etcd (Core OS)

toc::[]


[[Etcd]]
== Integration with etcd (Extension Module)
Tamaya _Etcd_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.

=== What functionality this module provides ?

Tamaya _Etcd_ provides artifacts, which allow using link:https://github.com/coreos/etcd[etcd] as a
configuration backend. Basically the module adds a read-only property source (+EtcdPropertySource+). If
the _tamaya-mutable-config_ extension is loaded it is alos possible to write configuration
changes to _etcd_ using +MutableConfiguration+.


=== Compatibility

The module is based on Java 8.


=== Installation

To use _etcd_ as a configuration backend you only must add the corresponding dependency to
your module:

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


=== The Functionality Provided

Tamaya's _etcd_ integration provides basically the following artifacts:

* The +org.apache.tamaya.etcd.EtcdPropertySource+ is a ready-to-use +PropertySource+ with a default ordinal of 100 and
  the name 'etcd'.
* The +org.apache.tamaya.etcd.AbstractEtcdPropertySource+ is a abstract base +PropertySource+ you can use to
  implement your own etcd propertysource.


=== The EtcdPropertySource

The +EtcdPropertySource+ is a ready-to-use property source implementation for etcd. For use you must simply register it
with the Java `ServiceLoader` od include it in a +PropertySourceProvider+. It provides:

* a etcd based property source implementation.
* configurable caching of key/values.
* configuring a dedicated etcd directory ID to be used.
* The property source reads the +tamaya.etcd.server+ system or environment property to evaluate the etcd servers
  (comma separated). The API hereby just performs a Round-Robin through the list of
  configured servers. Without any configuration +http://127.0.0.1:4001+ is used. If no connection to any etcd
  server can be established a warning will be logged, but deployment will not fail.
* Additionally with +tamaya.etcd.timeout+ system or environment property you can configure the connection timeout
  in seconds.

=== The AbstractEtcdPropertySource

The +AbstractEtcdPropertySource+ is the base class used by +EtcdPropertySource+. Use it to implement your own custom
etcd property source.