** 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.
java client, based on jclouds, to interact with Etcd's v2 REST API.
Client's can be built like so:
EtcdClient client = EtcdClient.builder()
.endPoint("http://127.0.0.1:2379") // Optional. Defaults to http://127.0.0.1:2379
.credentials("admin:password") // Optional.
.build();
Key createdKey = client.api().keysApi().createKey("keyName", "keyValue");
Can be sourced from jcenter like so:
<dependency>
<groupId>com.cdancy</groupId>
<artifactId>etcd-rest</artifactId>
<version>1.0.0</version>
<classifier>sources|javadoc|all</classifier> (Optional)
</dependency>
javadocs can be found via github pages here
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):
etcd.rest.endpointetcdRestEndpointETCD_REST_ENDPOINTETCD_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):
etcd.rest.credentialsetcdRestCredentialsETCD_REST_CREDENTIALS
etcd-rest credentials can take 1 of 2 forms:
- Colon delimited username and password: admin:password
- Base64 encoded username and password: YWRtaW46cGFzc3dvcmQ=
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=http://127.0.0.1:2379