Etcd common operation introduction



The easiest way to install is to download the pre compiled binary directly from the release page of etcd GitHub. Etcd officially provides different binary files for each system for developers to download according to their own system.

Download address:

After the download and decompression, there are two binaries in the directory,etcdas well asetcdctl。 amongetcdIs the binary file that runs the etcd service,etcdctlIs the official command line etcd client, usingetcdctlYou can access the etcd service from the command line.

takeetcdandetcdctlThese two files are soft chained to system environment variables$PATHUnder the corresponding directory, it is convenient to start the service. Of course, the purpose of the experiment is to directly switch the working directory to the directory just downloaded and run two files directly.

I downloaded the etcd file corresponding to Mac OS from GitHub. Execute the following command to see the version of etcd

➜  etcd-v3.3.17-darwin-amd64 ./etcd --version
etcd Version: 3.3.17
Git SHA: 6d8052314
Go Version: go1.12.9
Go OS/Arch: darwin/amd64
➜  etcd-v3.3.17-darwin-amd64 


Direct operationetcdCommand to start and run on the computeretcdservice

2019-10-22 13:15:32.244300 I | embed: listening for peers on http://localhost:2380
2019-10-22 13:15:32.244466 I | embed: listening for client requests on localhost:2379

Two lines of key information can be found in the output log of the startup command. After the etcd service is started, the communication port provided to the external client is 2379, while the communication port between members in the etcd service is 2380 (peer is the name of another member in the same etcd cluster).

Important options when starting a command:

-nameNode name, UUID by default
-data-dirThe directory where logs and snapshots are saved. The default is the current working directory
-addrPublished IP address and port. Default is
-bind-addrListening address for client connection, default to – addr configuration
-peersComma separated list of cluster members, such as
-peer-addrThe published IP address of cluster service communication is by default
-peer-bind-addrThe listening address of cluster service communication. The default is – peer addr configuration

The configuration file can also be set for the above configuration. The default is/etc/etcd/etcd.conf

Using etcd

etcdctlIs a command-line client, it provides a simple command, which can facilitate us to test the service or manually modify the database content. It is suggested that students who have just been exposed to etcd can first get familiar with the relevant operations through etcdctl. These operations correspond to the HTTP API provided by etcd.

adopt-hOptions can be seenetcdctlSupported operations.

➜  etcd-v3.3.17-darwin-amd64 ./etcdctl -h
   etcdctl - A simple command line client for etcd.

     backup          backup an etcd directory
     cluster-health  check the health of the etcd cluster
     mk              make a new key with a given value
     mkdir           make a new directory
     rm              remove a key or a directory
     rmdir           removes the key if it is an empty directory or a key-value pair
     get             retrieve the value of a key
     ls              retrieve a directory
     set             set the value of a key
     setdir          create a new directory or update an existing directory TTL
     update          update an existing key with a given value
     updatedir       update an existing directory
     watch           watch a key for changes
     exec-watch      watch a key for changes and exec an executable
     member          member add, remove and list subcommands
     user            user add, grant and revoke subcommands
     role            role add, grant and revoke subcommands
     auth            overall auth controls
     help, h         Shows a list of commands or help for one command

These operation commands are basically divided into key value library operation commands and behavior control commands.

Key library operation


Set the value of the key (or topic)

➜  etcd-v3.3.17-darwin-amd64 ./etcdctl set /root/test/keyOne "Hello etcd"
Hello etcd
➜  etcd-v3.3.17-darwin-amd64 

Supported options include:

--TTL '0' the timeout time (in seconds) of the key value. If it is not configured (the default is 0), it will never timeout
--Swap with value value if the current value of the key is value, perform the setting operation
--Swap with index '0' if the current index value of the key is the specified index, perform the setting operation


Get the value of the given key

➜  etcd-v3.3.17-darwin-amd64 ./etcdctl get /root/test/keyOne          
Hello etcd
➜  etcd-v3.3.17-darwin-amd64 

Error will be reported when trying to get the value not saved

➜  etcd-v3.3.17-darwin-amd64 ./etcdctl get /root/test/keyTwo
Error:  100: Key not found (/root/test/keyTwo) [11]
➜  etcd-v3.3.17-darwin-amd64 

The supported options are

--Sort sorts the results
--Consistent sends the request to the master node to ensure the consistency of the obtained content


Update the value stored in the given key

➜  etcd-v3.3.17-darwin-amd64 ./etcdctl update /root/test/keyOne "Hello World"
Hello World
➜  etcd-v3.3.17-darwin-amd64 

Also, an error will be reported when trying to update a value that does not exist

➜  etcd-v3.3.17-darwin-amd64 ./etcdctl update /root/test/keyTwo "Hello World"
Error:  100: Key not found (/root/test/keyTwo) [11]

The supported options are

--TTL '0' timeout in seconds, never timeout if not configured (default 0)


Delete the given key. If the key given in the command parameter does not exist, an error will be reported

➜  etcd-v3.3.17-darwin-amd64 ./etcdctl rm /root/test/keyOne              
PrevNode.Value: Hello World
➜  etcd-v3.3.17-darwin-amd64 
--Dir delete if key is an empty directory or key value pair
--Recursive delete directory and all subkeys
--With value check if existing values match
--With index '0' check if existing indexes match


Create a directory, whether it exists or not.

The supported options are

--TTL '0' timeout in seconds, never timeout if not configured (default 0)


Update a directory that already exists. The supported options are

--TTL '0' timeout in seconds, never timeout if not configured (default 0)


Lists the keys or subdirectories under the directory (root by default). The contents of subdirectories are not displayed by default.

Supported options include

--Sort sorts the output
--Recursive if there are subdirectories in the directory, the contents will be output recursively
-P for output as directory, add '/' at the end to distinguish

Behavior manipulation


Back up etcd data.

Supported options include

--Data directory of data dir etcd
--Backup dir backup to the specified path


Monitor the change of a key value. Once the key value is updated, it will output the latest value and exit.

for example

➜  etcd-v3.3.17-darwin-amd64 ./etcdctl set root/test/KeyThree "Hello etcd"
Hello etcd // set the value of root / test / keythree
//Monitor root / test / keythree, change its value to "Hello world" in other sessions, and receive the updated results
➜  etcd-v3.3.17-darwin-amd64 ./etcdctl watch  root/test/KeyThree --forever
Hello World

Supported options include

--Forever monitor until the user presses' Ctrl + C 'to exit
--After index '0' is monitored until the index is specified
--Recursive returns all key values and subkey values


Monitor the change of a key value. Once the key value is updated, execute the given command.

For example, the user updates the testkey key value.

➜ etcd-v3.3.17-darwin-amd64 ./etcdctl exec-watch testkey -- sh -c 'ls'

Supported options include

--After index '0' is monitored until the index is specified
--Recursive returns all key values and subkey values


List, add, and delete etcd instances to the etcd cluster through the list, add, and remove commands.

For example, after starting an etcd service instance locally, you can view it with the following command.

➜  etcd-v3.3.17-darwin-amd64 ./etcdctl member list
8e9e05c52164694d: name=default peerURLs=http://localhost:2380 clientURLs=http://localhost:2379 isLeader=true
➜  etcd-v3.3.17-darwin-amd64