Skip to content
Java client for working with etcd's v2 REST API
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

** As of 12/20/2016 this project is in legacy mode. Version 1.0.0 is intended to be the final release unless any bugs are reported. There are currently no plans in-flight to support the v3 api though I might pick up that work at sometime in the future, time permitting of course. If anyone wants to take on the work to support the v3 api I would be more than happy to help and mentor.

Build Status Download


alt tag

java client, based on jclouds, to interact with Etcd's v2 REST API.

Setup and How to use

Client's can be built like so:

  EtcdClient client = EtcdClient.builder()
  .endPoint("") // Optional. Defaults to
  .credentials("admin:password") // Optional.

  Key createdKey = client.api().keysApi().createKey("keyName", "keyValue");

Latest release

Can be sourced from jcenter like so:

  <classifier>sources|javadoc|all</classifier> (Optional)


javadocs can be found via github pages here

Property based setup

Client's do NOT need supply the endPoint or credentials as part of instantiating the EtcdClient object. Instead one can supply them through system properties, environment variables, or a combination of the 2. System properties will be searched first and if not found we will attempt to query the environment.

Setting the endpoint can be done with any of the following (searched in order):

  • etcdRestEndpoint
  • ETCD_LISTEN_CLIENT_URLS (first in list that is reachable will be used)
  • ETCD_ADVERTISE_CLIENT_URLS (first in list that is reachable will be used)

Setting the credentials can be done with any of the following (searched in order):

  • etcdRestCredentials


etcd-rest credentials can take 1 of 2 forms:

  • Colon delimited username and password: admin:password
  • Base64 encoded username and password: YWRtaW46cGFzc3dvcmQ=

Understanding ErrorMessage

Instead of throwing an exception most objects will have an attached ErrorMessage. It is up to the user to check the handed back object to see if the ErrorMessage is non-null before proceeding.

The message attribute of ErrorMessage is what etcd hands back to us when something fails. In some cases the message may be expected (e.g. Key already exists) and in others not (e.g. User HelloWorld already exists). Using the example above one might proceed like this:

  Key createdKey = client.api().keysApi().createKey("keyName", "keyValue");
  if (createdKey.errorMessage() != null) {
      // at this point we know something popped on the server-side.
      // now decide whether we care or not.
      if (createdKey.errorMessage().message().contains("Key already exists")) {
          // ignore 
      } else {
          throw new Exception("Unexpected error: " + createdKey.errorMessage().message());


The mock and live tests provide many examples that you can use in your own code.


  • jclouds - used as the backend for communicating with Etcd's REST API
  • AutoValue - used to create immutable value types both to and from the etcd program


Running mock tests can be done like so:

./gradlew clean build mockTest

Running integration tests can be done like so (requires docker):

./gradlew clean build integTest

Running integration tests without invoking docker can be done like so:

./gradlew clean build integTest -PbootstrapDocker=false -PtestEtcdEndpoint= 

Projects leveraging this library

Additional Resources

You can’t perform that action at this time.