Etcd.jl

A Julia Etcd client for the etcd-v2 REST api.

NOTE: Responses from the etcd server containing valid json are parsed into julia Dicts and Arrays, while a String representation is returned for all other successful HTTP requests. For a detailed summary of the etcd responses please review the etcd api documentation.

Quickstart

julia> Pkg.add("Etcd")

julia> using Etcd

Configure the Etcd server

The library defaults to Etcd server at 127.0.0.1:2379.

cli = Etcd.connect("127.0.0.1", 2379, "v2")

Or you can specify the server ip address and port number.

cli = Etcd.connect("172.17.42.1", 5001)

Using Etcd Client

Get all machines in the cluster

julia> Etcd.connect("127.0.0.1", 2379, "v2")

julia> machines(cli)

Setting Key Values

cli = Etcd.connect("127.0.0.1", 2379, "v2")

Set a value on the /foo/bar key:

julia> set(cli, "/foo/bar", "Hello World")

Set a value on the /foo/bar key with a value that expires in 60 seconds:

julia> set(cli, "/foo/bar", "Hello World", ttl=60)

Note that the ttl value can be set with all the following commands by specifying ttl=ttl_expiry_time_in_seconds

Conditionally set a value on /foo/bar if the previous value was "Hello world". test_and_set is an alias for compare_and_swap.

julia> cas(cli, "/foo/bar", "Goodbye Cruel World", prev_value="Hello World")

You can also conditionally set a value based on the previous etcd index. Conditionally set a value on /foo/bar if the previous etcd index was 1818:

julia> cas(cli, "/foo/bar"," Goodbye Cruel World", prev_index=1818)

Create a new key /foo/boo, only if the key did not previously exist:

julia> create(cli, "/foo/boo", "Hello World")

Create a new dir /fooDir, only if the directory did not previously exist:

julia> createdir(cli, "/fooDir")

Update an existing key /foo/bar, only if the key already existed:

julia> update(cli, "/foo/boo", "Merhaba")

You can also Create (createdir) or update (updatedir) a directory.

Retrieving key values

Get the current value for a single key in the local etcd node:

julia> get(cli,"/foo/bar")

Add recursive=true to recursively list sub-directories.

Check for existence of a key:

julia> exists(cli,"/foo/bar")
true

Deleting keys

Delete a key:

julia> createdir(cli, "/foo/qux")
julia> delete(cli, "/foo/boo")

Delete an empty directory:

julia> deletedir(cli, "/foo/qux")

Recursively delete a key and all child keys:

julia> get(cli, "/foo", recursive=true)

julia> deletedir(cli, "/foo", recursive=true)

julia> get(cli, "/foo", recursive=true)

Conditionally delete /foo/bar if the previous value was "Hello world":

julia> create(cli, "/foo/bar", "bar value")

julia> cad(cli, "/foo/bar", prev_value="bar value")

Conditionally delete /foo/bar if the previous etcd index was 1849:

julia>create(cli, "/foo/bar", "Hello World")

julia> cad(cli, "/foo/bar", prev_index=1849)

Watching for changes

You can also create asynchronous watch routines with watch or watchloop. These methods will return the executed watch Task.

Watch for only the next change on a key:

julia> t = watch(resp -> println("I'm watching you: $resp"), cli, "/foo/bar")

To continuously watch a key:

julia> t = watchloop(cli, "/foo/bar"; recursive=true) do resp
    # Run some code with response
end

A termination condition (a Function which takes the etcd response and returns a Bool) can be used to exit the watch loop:

julia> predicate(r) = r["node"]["modifiedIndex"] > 5

julia> t = watchloop(cli, "/foo", predicate; recursive=true) do resp
    # Run some code with response
end

You can also specify the following options:

recursive=true to watch the key and all it's children.
wait_index to watch starting with the provided index.

Getting cluster information

You can retrieve Etcd stats by specifying one of store, self or leader.

For example to get the store stats:

julia> stats(etcd, "store")

You can also get the current leader with:

julia> leader(etcd)

or a list of members with:

julia> members(etcd)

Logging

To aid development and debugging Etcd supports Memento logging of HTTP response bodies.

To get etcd HTTP debug logs run:

julia> using Memento

julia> Memento.config("debug"; fmt="[{level}] {msg}")
Logger(root)

julia> set(cli, "/foo/bar", "Hello World")
[debug] {"action":"set","node":{"key":"/foo/bar","value":"Hello World","modifiedIndex":4,"createdIndex":4}}