You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tamaya.apache.org by an...@apache.org on 2016/02/27 22:02:27 UTC
[08/10] incubator-tamaya git commit: TAMAYA-143: Added docs for
consul support.
TAMAYA-143: Added docs for consul support.
Project: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/commit/b3535cef
Tree: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/tree/b3535cef
Diff: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/diff/b3535cef
Branch: refs/heads/master
Commit: b3535cef3541120eac3577652bfabae25b37d469
Parents: 2dfa4d8
Author: anatole <an...@apache.org>
Authored: Sat Feb 27 21:59:54 2016 +0100
Committer: anatole <an...@apache.org>
Committed: Sat Feb 27 21:59:54 2016 +0100
----------------------------------------------------------------------
src/site/asciidoc/extensions/mod_consul.adoc | 172 +++-------------------
1 file changed, 21 insertions(+), 151 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/b3535cef/src/site/asciidoc/extensions/mod_consul.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/extensions/mod_consul.adoc b/src/site/asciidoc/extensions/mod_consul.adoc
index 1a0d1f6..497da89 100644
--- a/src/site/asciidoc/extensions/mod_consul.adoc
+++ b/src/site/asciidoc/extensions/mod_consul.adoc
@@ -15,12 +15,12 @@
// specific language governing permissions and limitations
// under the License.
-= Apache Tamaya -- Extension: Integration with etcd (Core OS)
+= Apache Tamaya -- Extension: Integration with consul (Hashicorp)
:name: Tamaya
-:rootpackage: org.apache.tamaya.integration.etcd
-:title: Apache Tamaya Extension: Integration with etcd service
-:revdate: January 2016
+:rootpackage: org.apache.tamaya.integration.consul
+:title: Apache Tamaya Extension: Integration with consul service
+:revdate: February 2016
:authorinitials: ATR
:author: Anatole Tresch
:email: <an...@apache.org>
@@ -41,11 +41,11 @@ toc::[]
:numbered!:
<<<
[[Optional]]
-== Integration with etcd (Extension Module)
+== Integration with consul (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
+The Tamaya consul integration module provides different artifacts which allows integration of Apachae Tamaya
+configuration with consul. Basically the module supports read-only integration (as a +ConsulPropertySource+ as well
as a support for +MutableConfiguration+ as defined by the +tamaya-mutable-config+ extension module.
@@ -62,7 +62,7 @@ To benefit from configuration builder support you only must add the correspondin
-----------------------------------------------
<dependency>
<groupId>org.apache.tamaya.ext</groupId>
- <artifactId>tamaya-etcd</artifactId>
+ <artifactId>tamaya-consul</artifactId>
<version>{tamayaVersion}</version>
</dependency>
-----------------------------------------------
@@ -70,154 +70,24 @@ To benefit from configuration builder support you only must add the correspondin
=== The Extensions Provided
-ETcd integration comes basically with 2 artifacts:
+Consul 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 +org.apache.tamaya.etcd.ConsulPropertySource+ is a +PropertySource+ with a default ordinal of 100 and the name
+ 'consul', which is automatically registered.
+* If the +tamaya-mutable-config+ module is loaded it is possible to write property values back into the consul cluster,
+ by accessing a +MutableConfiguration+ using the URI +config:consul+.
-=== 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:
+=== The ConsulPropertySource
-[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 requires the etcd servers to be used to be configured. This
+The +ConsulPropertySource+ is automatically registered and allows the consul servers to be used to be configured. 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 container cluster:
+in microservice containers to connect with the according consul cluster:
-* The property source reads the +tamaya.etcd.server.urls+ system property to evaluate possible etcd servers
+* The property source reads the +tamaya.consul.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
+ 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.
-* 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+.
\ No newline at end of file
+* The +ConsulPropertySource+ finally also allows the values read from the consul cluster to be mapped to prefixed
+ context. This can be activated by setting the +-Dtamaya.consul.prefix=<PREFIX>+ system property. E.g. when the prefix is
+ set to +cluster-config.+ a consul key of +host:known/all+ is mapped to +cluster-config.host:known/all+.
\ No newline at end of file