22.3　使用etcdctl客户端

etcdctl是Etcd官方提供的命令行客户端，它支持一些基于HTTP API封装好的命令，供用户直接跟Etcd服务打交道，而无需基于HTTP API的方式。当然，这些命令跟HTTP API实际上是对应的，最终效果上并无不同之处。

某些场景下使用etcdctl将十分方便。例如用户需要对Etcd服务进行简单测试或者手动来修改数据库少量内容；也推荐在刚接触Etcd时通过etcdctl命令来熟悉Etcd支持的相关功能。

Etcd项目二进制发行包中已经包含了etcdctl工具，没有的话，可以从github.com/coreos/etcd/releases手动下载。

etcdctl的命令格式为：

$ etcdctl [全局选项]命令[命令选项] [命令参数]

全局选项参数见表22-5。

表22-5　etcdctl的命令全局选项参数

支持的命令大体上分为数据类操作和非数据类操作两类。

Etcd作为一个分布式数据库，类似ZooKeeper采用了类似文件目录的结构，数据类操作基本围绕对文件（即某个键）或目录进行。大家可以对比Linux的文件和目录操作命令，会发现两者之间的相似性。非数据类操作主要是Etcd提供的系统配置、权限管理等。参见表22-6和表22-7。

数据类操作命令见表22-6，非数据类操作见表22-7。

表22-6　Etcd数据类操作命令

表22-7　Etcd非数据类操作命令

下面分别来看下各个操作的主要用法和功能。

22.3.1　数据类操作

数据类操作围绕对键值和目录的CRUD（符合REST风格的一套操作：Create）完整生命周期的管理。

Etcd在键的组织上采用了层次化的空间结构（类似于文件系统中目录的概念），用户指定的键可以为单独的名字，如testkey，此时实际上放在根目录/下面，也可以为指定目录结构，如cluster1/node2/testkey，则将创建相应的目录结构。

提示

CRUD即Create、Read、Update、Delete，是符合REST风格的一套API操作规范。

1.set

设置某个键的值为给定值。例如：

$ etcdctl set /testdir/testkey "Hello world"
Hello world

支持的选项包括：

·—ttl'0'。键值的超时时间（单位为秒），不配置（默认为0）则永不超时

·—swap-with-value value。若该键现在的值是value，则进行设置操作

·—swap-with-index'0'。若该键现在的索引值是指定索引，则进行设置操作

注意

—ttl选项十分有用。在分布式环境中，系统往往是不可靠的，在基于Etcd设计分布式锁的时候，可以通过超时时间避免出现发生死锁的情况。

2.get

获取指定键的值。例如：

$ etcdctl set testkey hello
hello
$ etcdctl update testkey world
world

当键不存在时，则会报错。例如：

$ etcdctl get testkey2
Error:  100: Key not found (/testkey2) [1]

支持的选项为—sort，对返回结果进行排序。

3.update

当键存在时，更新值内容。例如：

$ etcdctl set testkey hello
hello
$ etcdctl update testkey world
world

当键不存在时，则会报错。例如：

$ etcdctl update testkey2 world
Error:  100: Key not found (/testkey2) [1]

支持的选项为—ttl'0'，超时时间（单位为秒），不配置（默认为0）则永不超时。

4.mk

如果给定的键不存在，则创建一个新的键值。例如：

$ etcdctl mk /testdir/testkey "Hello world"
Hello world

当键存在的时候，执行该命令会报错，例如：

$ etcdctl set testkey "Hello world"
Hello world
$ ./etcdctl mk testkey "Hello world"
Error:  105: Key already exists (/testkey) [2]

支持的选项为—ttl'0'，超时时间（单位为秒），不配置（默认为0）则永不超时。

5.rm

删除某个键值。例如：

$ etcdctl rm testkey

当键不存在时，则会报错。例如：

$ etcdctl rm testkey2
Error:  100: Key not found (/testkey2) [8]

支持的选项为：

—dir——如果键是个空目录或者是键值对则删除；

—recursive——删除目录和所有子键；

—with-value——检查现有的值是否匹配；

—with-index'0'——检查现有的index是否匹配。

6.watch

监测一个键值的变化，一旦键值发生更新，就会输出最新的值并退出。

例如，用户更新testkey键值为Hello world。

$ etcdctl watch testkey
Hello world

支持的选项包括：

—forever——一直监测，直到用户按CTRL+C退出；

—after-index'0'——在指定index之前一直监测；

—recursive——返回所有的键值和子键值。

7.exec-watch

监测一个键值的变化，一旦键值发生更新，就执行给定命令。这个功能十分强大，很多时候可以用于实时根据键值更新本地服务的配置信息，并重新加载服务。可以实现分布式应用配置的自动分发。

例如，一旦检测到testkey键值被更新，则执行ls命令。

$ etcdctl exec-watch testkey -- sh -c 'ls'
default.etcd
Documentation
etcd
etcdctl
etcd-migrate
README-etcdctl.md
README.md

支持的选项包括：

—after-index'0'——在指定index之前一直监测；

—recursive——返回所有的键值和子键值。

8.ls

列出目录（默认为根目录）下的键或者子目录，默认不显示子目录中内容。例如：

$ ./etcdctl set testkey 'hi'
hi
$ ./etcdctl set dir/test 'hello'
hello
$ ./etcdctl ls
/testkey
/dir
$ ./etcdctl ls dir
/dir/test

支持的选项包括：

·—sort——将输出结果排序

·—recursive——如果目录下有子目录，则递归输出其中的内容

·-p——对于输出为目录，在最后添加/进行区分

9.mkdir

如果给定的键目录不存在，则创建一个新的键目录。例如：

$ etcdctl mkdir testdir

当键目录存在的时候，执行该命令会报错，例如：

$ etcdctl mkdir testdir
$ etcdctl mkdir testdir
Error:  105: Key already exists (/testdir) [7]

支持的选项为—ttl'0'，超时时间（单位为秒），不配置（默认为0）则永不超时。

10.rmdir

删除一个空目录，或者键值对。若目录不空，会报错，例如：

$ etcdctl set /dir/testkey hi
hi
$ etcdctl rmdir /dir
Error:  108: Directory not empty (/dir) [13]

11.setdir

创建一个键目录，无论存在与否。实际上，目前版本当目录已经存在的时候会报错。例如：

$ etcdctl setdir /test/test
$ etcdctl ls --recursive
/test
/test/test

支持的选项为—ttl'0'，超时时间（单位为秒），不配置（默认为0）则永不超时。

12.updatedir

更新一个已经存在的目录的属性（目前只有存活时间），例如：

$ etcdctl mkdir /test/test --ttl 100
$ etcdctl updatedir /test/test --ttl 200

支持的选项为—ttl'0，存活时间（单位为秒），不配置（默认为0）则永不超时。

22.3.2　非数据类操作

非数据类操作不直接对数据本身进行管理，而是负责围绕集群自身的一些配置。

1.backup

备份Etcd的配置状态数据目录。

支持的选项包括：

·—data-dir——要进行备份的Etcd的数据存放目录；

·—backup-dir——备份数据到指定路径。

例如，备份默认配置的信息到当前路径下的tmp子目录：

$ etcdctl backup --data-dir default.etcd --backup-dir tmp

可以查看tmp目录下面多了一个member目录：

$ ls tmp/member
snap  wal

其中，snap为快照目录，保存节点状态快照文件（注意这些快照文件定期生成）；wal保存了数据库预写日志信息。

注意

预写日志要求数据库在发生实际提交前必须先将操作写入日志，可以保障系统在崩溃后根据日志回复状态。

2.cluster-health

查看Etcd集群的健康状态。例如：

$ etcdctl cluster-health
member ce2a822cea30bfca is healthy: got healthy result from http://localhost:2379
cluster is healthy

支持的选项包括—forever，每隔10秒钟检查一次，直到手动终止（通过Ctrl+C命令）。

3.member

通过list、add、remove等子命令列出、添加、删除Etcd实例到Etcd集群中。

例如本地启动一个Etcd服务实例后，可以用如下命令进行查看默认的实例成员：

$ etcdctl member list
ce2a822cea30bfca: name=default peerURLs=http://localhost:2380,http://localhost: 
    7001 clientURLs=http://localhost:2379,http://localhost:4001

4.import

导入旧版本（v0.4.*）的快照文件到系统。

支持的选项包括：

·—snap——快照文件路径；

·—hidden'—hidden option—hidden option'——隐藏导入的键值空间信息；

·-c'10'——并发导入的客户端数。

例如，导入通过backup命令导出的快照文件：

$ etcdctl import --snap tmp/member/snap/0000000000000003-0000000000061aa8.snap
starting to import snapshot tmp/member/snap/0000000000000003-0000000000061aa8.
    snap with 10 clients
entering dir: /
copying key: /key 1
finished importing 1 keys

5.user

对用户进行管理，包括一系列子命令：

·add——添加一个用户；

·get——查询用户细节；

·list——列出所有用户；

·remove——删除用户；

·grant——添加用户到角色；

·revoke——删除用户角色；

·passwd——修改用户的密码。

默认情况下，需要先创建（启用）root用户作为etcd集群的最高权限管理员：

$ etcdctl user add root 
New password:

创建一个testuser用户，会提示输入密码：

$ etcdctl user add testuser
New password:

分配某些已有角色给用户：

$ etcdctl user grant testuser -roles testrole

6.role

对用户角色进行管理，包括一系列子命令：

add——添加一个角色；

get——查询角色细节；

list——列出所有用户角色；

remove——删除用户角色；

grant——添加路径到角色控制，可以为read、write或者readwrite；

revoke——删除某路径的用户角色信息。

默认带有root、guest两种角色，前者为全局最高权限，后者为不带验证情况下的用户。

例如：

$ etcdctl role add testrole
$ etcdctl role grant testrole -path '/key/*' -read

7.auth

是否启用访问验证。enable为启用，disable为禁用。

例如，在root用户创建后，启用认证：

$ etcdctl auth enable