| :jbake-type: page |
| :jbake-status: published |
| |
| = Apache Tamaya -- Extension: Integration with etcd (Core OS) |
| |
| toc::[] |
| |
| |
| [[Optional]] |
| == Integration with etcd (Extension Module) |
| === Overview |
| |
| The Tamaya etcd integration module provides different artifacts which allows integration of Apachae Tamaya |
| configuration with etcd. Basically the module supports read-only integration (as a +EtcdPropertySource+ as well |
| as a support for +MutableConfiguration+ as defined by the +tamaya-mutable-config+ extension module. |
| |
| |
| === Compatibility |
| |
| The module is based on Java 7, so it will not run on Java 7 and beyond. |
| |
| |
| === Installation |
| |
| To benefit from configuration builder support you only must add the corresponding dependency to your module: |
| |
| [source, xml] |
| ----------------------------------------------- |
| <dependency> |
| <groupId>org.apache.tamaya.ext</groupId> |
| <artifactId>tamaya-etcd</artifactId> |
| <version>{tamaya_version}</version> |
| </dependency> |
| ----------------------------------------------- |
| |
| |
| === The Extensions Provided |
| |
| ETcd integration comes basically with 2 artifacts: |
| |
| * The +org.apache.tamaya.etcd.EtcdAccessor+ can be configured with a an url targeting an etcd server's REST endpoint root. |
| (+org.apache.tamaya.etcd.EtcdAccessor+). The accessor basically provides a simple Java API for communicating |
| with etcd server. The accessor hereby allows reading of single properties, or whole subtrees. Also the basic non |
| atomic write methods are implemented. |
| * The +org.apache.tamaya.etcd.EtcdPropertySource+ is a +PropertySource+ with a default ordinal of 100 and the name |
| 'etcd', which is automatically registered. |
| * If the +tamaya-mutable-config+ module is loaded it is possible to write property values back into the etcd cluster, |
| by accessing a +MutableConfiguration+ using the URI +config:etcd+. |
| |
| === The EtcdAccessor |
| |
| The accessor mentioned implements the basic read and write API for communicating with an etcd configuration cluster. |
| Hereby the accessor also provides etcd specific data such as +createdIndex, modifiedIndex, ttl+ in the +Map+ |
| returned. Hereby the concept of etcd is used where keys starting with an '_' will be hidden from the overall |
| properties map, being only directly/explicitly accessible: |
| |
| [source, java] |
| ----------------------------------------------- |
| public class EtcdAccessor { |
| |
| /** |
| * Creates a new instance with the basic access url. |
| * @param server server url, e.g. {@code http://127.0.0.1:4001}. |
| * @throws MalformedURLException |
| */ |
| public EtcdAccessor(String server) throws MalformedURLException; |
| |
| /** |
| * Get the etcd server version. |
| * @return the etcd server version, never null. |
| */ |
| public String getVersion(); |
| |
| /** |
| * Ask etcd for s aingle key, value pair. Hereby the response returned from etcd: |
| * <pre> |
| * key=value |
| * _key.source=[etcd]http://127.0.0.1:4001 |
| * _key.createdIndex=12 |
| * _key.modifiedIndex=34 // optional |
| * _key.ttl=300 // optional |
| * _key.expiration=... // optional |
| * </pre> |
| * @param key the requested key |
| * @return the mapped result, including meta-entries. |
| */ |
| public Map<String,String> get(String key); |
| |
| /** |
| * Creates/updates an entry in etcd without any ttl set. |
| * The response is as follows: |
| * <pre> |
| * key=value |
| * _key.source=[etcd]http://127.0.0.1:4001 |
| * _key.createdIndex=12 |
| * _key.modifiedIndex=34 // optional |
| * _key.prevNode.createdIndex=12 // optional |
| * _key.prevNode.modifiedIndex=34 // optional |
| * </pre> |
| * @param key the property key, not null |
| * @param value the value to be set |
| * @return the result map as described above. |
| */ |
| public Map<String,String> set(String key, String value); |
| |
| /** |
| * Creates/updates an entry in etcd. The response is as follows: |
| * <pre> |
| * key=value |
| * _key.source=[etcd]http://127.0.0.1:4001 |
| * _key.createdIndex=12 |
| * _key.modifiedIndex=34 // optional |
| * _key.ttl=300 // optional |
| * _key.expiry=... // optional |
| * _key.prevNode.createdIndex=12 // optional |
| * _key.prevNode.modifiedIndex=34 // optional |
| * _key.prevNode.ttl=300 // optional |
| * _key.prevNode.expiration=... // optional |
| * </pre> |
| * @param key the property key, not null |
| * @param value the value to be set |
| * @param ttlSeconds the ttl in seconds (optional) |
| * @return the result map as described above. |
| */ |
| public Map<String,String> set(String key, String value, Integer ttlSeconds); |
| |
| |
| /** |
| * Deletes a given key. The response is as follows: |
| * <pre> |
| * _key.source=[etcd]http://127.0.0.1:4001 |
| * _key.createdIndex=12 |
| * _key.modifiedIndex=34 |
| * _key.ttl=300 // optional |
| * _key.expiry=... // optional |
| * _key.prevNode.createdIndex=12 // optional |
| * _key.prevNode.modifiedIndex=34 // optional |
| * _key.prevNode.ttl=300 // optional |
| * _key.prevNode.expiration=... // optional |
| * _key.prevNode.value=... // optional |
| * </pre> |
| * @param key the key to be deleted. |
| * @return the response mpas as described above. |
| */ |
| public Map<String,String> delete(String key); |
| |
| |
| /** |
| * Access regular Tamaya properties map as follows: |
| * <pre> |
| * key1=myvalue |
| * _key1.source=[etcd]http://127.0.0.1:4001 |
| * _key1.createdIndex=12 |
| * _key1.modifiedIndex=34 // optional |
| * _key1.ttl=300 // optional |
| * _key1.expiration=... // optional |
| * |
| * key2=myvaluexxx |
| * _key2.source=[etcd]http://127.0.0.1:4001 |
| * _key2.createdIndex=12 |
| * |
| * key3=val3 |
| * _key3.source=[etcd]http://127.0.0.1:4001 |
| * _key3.createdIndex=12 |
| * _key3.modifiedIndex=2 |
| * </pre> |
| */ |
| public Map<String,String> getProperties(String directory, boolean recursive); |
| |
| } |
| ----------------------------------------------- |
| |
| |
| === The EtcdPropertySource |
| |
| The +EtcdPropertySource+ is automatically registered and allows to configure the etcd servers to be used. This |
| enables to use e.g. in Docker environments the docker environment configuration mechanisms to configure Tamaya running |
| in microservice containers to connect with the according etcd cluster: |
| |
| * The property source reads the +tamaya.etcd.server.urls+ system and environment property to evaluate possible etcd servers |
| (comma separated), which can be connected to. On error the API 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. |
| * Additinoally also the |
| accessor allows to configure the socket/connection timeouts by setting +tamaya.etcd.timeout+ in seconds either as |
| system or environment property. |
| * The +EtcdPropertySource+ finally also allows the values read from the etcd cluster to be mapped to prefixed |
| context. This can be activated by setting the +-Dtamaya.etcd.prefix=<PREFIX>+ system property. E.g. when the prefix is |
| set to +cluster-config.+ a etcd key of +host:known/all+ is mapped to +cluster-config.host:known/all+. |
