etcdctl

etcdctl is a command line client for etcd. It can be used in scripts or for administrators to explore an etcd cluster.

Getting etcdctl

The latest release is available as a binary at Github along with etcd.

etcdctl can also be built from source using the build script found in the parent directory.

Configuration

--debug

output cURL commands which can be used to reproduce the request

--no-sync

don't synchronize cluster information before sending request
Use this to access non-published client endpoints
Without this flag, values from --endpoint flag will be overwritten by etcd cluster when it does internal sync.

--output, -o

output response in the given format (simple, extended or json)
default: "simple"

--discovery-srv, -D

domain name to query for SRV records describing cluster endpoints
default: none
env variable: ETCDCTL_DISCOVERY_SRV

--peers

a comma-delimited list of machine addresses in the cluster
default: "http://127.0.0.1:2379"
env variable: ETCDCTL_PEERS

--endpoint

a comma-delimited list of machine addresses in the cluster
default: "http://127.0.0.1:2379"
env variable: ETCDCTL_ENDPOINT
Without --no-sync flag, this will be overwritten by etcd cluster when it does internal sync.

--cert-file

identify HTTPS client using this SSL certificate file
default: none
env variable: ETCDCTL_CERT_FILE

--key-file

identify HTTPS client using this SSL key file
default: none
env variable: ETCDCTL_KEY_FILE

--ca-file

verify certificates of HTTPS-enabled servers using this CA bundle
default: none
env variable: ETCDCTL_CA_FILE

--username, -u

provide username[:password] and prompt if password is not supplied
default: none
env variable: ETCDCTL_USERNAME

--timeout

connection timeout per request
default: "1s"

--total-timeout

timeout for the command execution (except watch)
default: "5s"

Usage

Setting Key Values

Set a value on the /foo/bar key:

$ etcdctl set /foo/bar "Hello world"
Hello world

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

$ etcdctl set /foo/bar "Hello world" --ttl 60
Hello world

Conditionally set a value on /foo/bar if the previous value was "Hello world":

$ etcdctl set /foo/bar "Goodbye world" --swap-with-value "Hello world"
Goodbye world

Conditionally set a value on /foo/bar if the previous etcd index was 12:

$ etcdctl set /foo/bar "Goodbye world" --swap-with-index 12
Goodbye world

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

$ etcdctl mk /foo/new_bar "Hello world"
Hello world

Create a new in-order key under dir /fooDir:

$ etcdctl mk --in-order /fooDir "Hello world"

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

$ etcdctl mkdir /fooDir

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

$ etcdctl update /foo/bar "Hola mundo"
Hola mundo

Create or update a directory called /mydir:

$ etcdctl setdir /mydir

Retrieving a key value

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

$ etcdctl get /foo/bar
Hello world

Get the value of a key with additional metadata in a parseable format:

$ etcdctl -o extended get /foo/bar
Key: /foo/bar
Modified-Index: 72
TTL: 0
Etcd-Index: 72
Raft-Index: 5611
Raft-Term: 1

Hello World

Listing a directory

Explore the keyspace using the ls command

$ etcdctl ls
/akey
/adir
$ etcdctl ls /adir
/adir/key1
/adir/key2

Add --recursive to recursively list subdirectories encountered.

$ etcdctl ls --recursive
/akey
/adir
/adir/key1
/adir/key2

Directories can also have a trailing / added to output using -p.

$ etcdctl ls -p
/akey
/adir/

Deleting a key

Delete a key:

$ etcdctl rm /foo/bar

Delete an empty directory or a key-value pair

$ etcdctl rmdir /path/to/dir

$ etcdctl rm /path/to/dir --dir

Recursively delete a key and all child keys:

$ etcdctl rm /path/to/dir --recursive

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

$ etcdctl rm /foo/bar --with-value "Hello world"

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

$ etcdctl rm /foo/bar --with-index 12

Watching for changes

Watch for only the next change on a key:

$ etcdctl watch /foo/bar
Hello world

Continuously watch a key:

$ etcdctl watch /foo/bar --forever
Hello world
.... client hangs forever until ctrl+C printing values as key change

Continuously watch a key, starting with a given etcd index:

$ etcdctl watch /foo/bar --forever --index 12
Hello world
.... client hangs forever until ctrl+C printing values as key change

Continuously watch a key and exec a program:

$ etcdctl exec-watch /foo/bar -- sh -c "env | grep ETCD"
ETCD_WATCH_ACTION=set
ETCD_WATCH_VALUE=My configuration stuff
ETCD_WATCH_MODIFIED_INDEX=1999
ETCD_WATCH_KEY=/foo/bar
ETCD_WATCH_ACTION=set
ETCD_WATCH_VALUE=My new configuration stuff
ETCD_WATCH_MODIFIED_INDEX=2000
ETCD_WATCH_KEY=/foo/bar

Continuously and recursively watch a key and exec a program:

$ etcdctl exec-watch --recursive /foo -- sh -c "env | grep ETCD"
ETCD_WATCH_ACTION=set
ETCD_WATCH_VALUE=My configuration stuff
ETCD_WATCH_MODIFIED_INDEX=1999
ETCD_WATCH_KEY=/foo/bar
ETCD_WATCH_ACTION=set
ETCD_WATCH_VALUE=My new configuration stuff
ETCD_WATCH_MODIFIED_INDEX=2000
ETCD_WATCH_KEY=/foo/barbar

Return Codes

The following exit codes can be returned from etcdctl:

0    Success
1    Malformed etcdctl arguments
2    Failed to connect to host
3    Failed to auth (client cert rejected, ca validation failure, etc)
4    400 error from etcd
5    500 error from etcd

Endpoint

If the etcd cluster isn't available on http://127.0.0.1:2379, specify a --endpoint flag or ETCDCTL_ENDPOINT environment variable. One endpoint or a comma-separated list of endpoints can be listed. This option is ignored if the --discovery-srv option is provided.

ETCDCTL_ENDPOINT="http://10.0.28.1:4002" etcdctl set my-key to-a-value
ETCDCTL_ENDPOINT="http://10.0.28.1:4002,http://10.0.28.2:4002,http://10.0.28.3:4002" etcdctl set my-key to-a-value
etcdctl --endpoint http://10.0.28.1:4002 my-key to-a-value
etcdctl --endpoint http://10.0.28.1:4002,http://10.0.28.2:4002,http://10.0.28.3:4002 etcdctl set my-key to-a-value

Username and Password

If the etcd cluster is protected by authentication, specify username and password using the --username or ETCDCTL_USERNAME environment variable. When --username flag or ETCDCTL_USERNAME environment variable doesn't contain password, etcdctl will prompt password in interactive mode.

ETCDCTL_USERNAME="root:password" etcdctl set my-key to-a-value

DNS Discovery

To discover the etcd cluster through domain SRV records, specify a --discovery-srv flag or ETCDCTL_DISCOVERY_SRV environment variable. This option takes precedence over the --endpoint flag.

ETCDCTL_DISCOVERY_SRV="some-domain" etcdctl set my-key to-a-value
etcdctl --discovery-srv some-domain set my-key to-a-value

Project Details

Versioning

etcdctl uses semantic versioning. Releases will follow lockstep with the etcd release cycle.

License

etcdctl is under the Apache 2.0 license. See the LICENSE file for details.

READMEv2.md 7.7 KB Permalink History Raw