Using etcd3 Features

etcdctl

Using etcdctl with etcd API version 3 is a quick way to explore the features of etcd3. First you will want to set the environment variables ETCDCTL_ENDPOINTS and ETCDCTL_USER to use your deployment's connection strings, and then set the environment variable to use the etcd API version 3 with export ETCDCTL_API=3.

export ETCDCTL_API=3
export ETCDCTL_ENDPOINTS=https://portal1130-24.brilliant-etcd-21.compose-34.composedb.com:20773,https://portal1142-25.brilliant-etcd-21.compose-34.composedb.com:20773
export ETCDCTL_USER=root:password

📘

etcd API versions

If you are running etcd3 on your deployment, you can only use v3 of the API. The v2 API is not supported.

Prefixes

To use directory keys in etcd3 use the --prefix option on the get command to query on the top-level directory.

etcdctl put /foo-service/container1 examplename
> OK

etcdctl get --prefix /foo-service
> /foo-service/container1
examplename

If adding more sub-directory keys and values, then the --prefix option will return all of them in the top-level directory.

etcdctl put /foo-service/container2 examplename2
> OK
etcdctl put /foo-service/container3 examplename3
> OK

etcdctl get --prefix /foo-service
> /foo-service/container1
examplename
/foo-service/container2
examplename2
/foo-service/container3
examplename3

Transactions

Transactions take a series of etcd commands and applies them all as a single, atomic transaction. The txn command is broken into three parts.

• define the key you would like to modify and the value it should be before modifying.
• if the comparison is successful, enter the commands to execute
• if the comparison is a failure, enter the commands to execute

If you use interactive mode: etcdctl txn -i the session will prompt for the parts.

etcdctl put key1 1
> OK

etcdctl txn -i
# compares:
mod("key1") > "0"
⏎
⏎
# success requests (get, put, delete):
put key1 "overwrote-key1"
>
>
# failure requests (get, put, delete):
>
>
SUCCESS

OK

To check that the new value got assigned to the key:

etcdctl get key1
> key1
overwrote-key1

To skip the prompts, use non-interactive mode.

etcdctl txn <<<'mod("key1") > "0"
>
> put key1 "overwrote-key1-again"
>
>
>
> '
SUCCESS

OK

etcdctl get key1
key1
overwrote-key1-again

Leases

etcd3 uses leases to manage temporary keys. A lease is created with a time-to-live (TTL) and then attached to a key at creation. One lease can be used for multiple keys. When the TTL on the lease expires, it deletes all associated keys. To create a lease, use grant with a number of seconds for TTL.

$ etcdctl lease grant 500
> lease 694d5cefe052b00d granted with TTL(500s)

Then create a key/pair with the --lease option.

$ etcdctl put foo1 bar1 --lease=694d5cefe052b00d
> OK

You can find out what keys are associated with a granted lease, along with the time remaining on the lease.

$ etcdctl lease timetolive 694d5cefe052b00d --keys
> lease 694d5cefe052b00d granted with TTL(500s), remaining(377s), attached keys([foo1])

After the time on a lease has expired, requesting the value of a key not return anything. If you try to provision a key on a lease that has already expired, it will return an error.

$ etcdctl lease grant 10
> lease 694d5cefe052b009 granted with TTL(10s)
$ etcdctl put foo1 bar1 --lease=694d5cefe052b009
> Error:  etcdserver: requested lease not found

Watchers

Keep track of changes to keys using the watch command. As an example, running it in one terminal window will keep the connection open and update with any changes to the key that it is watching. Updating the value of the key in a separate terminal will have the results displayed in both terminals.

#Terminal 1
$ etcdctl put greeting 'Hello World'
>Hello World

#Terminal 2
$ etcdctl watch greeting

#Terminal 1
$ etcdctl put greeting 'Hello Watcher'
>Hello Watcher

#Terminal 2
> PUT
greeting
Hello Watcher

The connection is left open, and continues to watch that key for subsequent changes.

The -i option (stands for interactive) allows watch to be updated with new keys to watch on the already open same connection. While running, it will accept new watch commands. For example, two keys 'snack' and 'dessert'.

$ etcdctl put snack chocolate
> OK
$ etcdctl put dessert cake
> OK

# In Terminal 2, watch 'dessert'.
$ etcdctl watch -i
watch dessert

# Update 'dessert' in Terminal 1
$ etcdctl put dessert pie
> OK

# Terminal 2 returns that update
> PUT
dessert
pie

# Then tell the watcher to watch the 'snack' key.
$ watch snack

# Update 'snack' in Terminal 1
$ etcdctl put snack cookies

# Terminal 2 returns that update
> PUT
snack
cookies

Still Need Help?

If this article didn't solve things, summon a human and get some help!