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_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_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 v2 and API v3
If you are running etcd3 on your deployment, you should use and v3 of the API.
If you are looking for examples of how to use API v2, please see the Using etcd2 Features page.
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 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
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
$ 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
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.
-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
If this article didn't solve things, summon a human and get some help!