Home

Etcd.jl

stable latest Build Status codecov

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:

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}}