etcdctl常用命令行
用户可以使用etcd的命令行工具etcdctl与etcd服务端进行交互。默认情况下,etcdctl使用v2的API,如需要使用v3的API,可以导入如下环境变量:
export ETCDCTL_API=3
key的常规操作
写入一个key
所有存储的key都通过Raft协议被复制到etcd集群的所有节点上,Raft协议保证了数据的一致性协议和可靠性。向一个key写入一个值最简单的一条命令如下所示:
etcdctl put foo bar
如果需要为这个key设置一个老化时间,比如10分钟,那么可以通过为它绑定一个“租约 lease”来实现,具体命令如下:
etcdctl lease grant 10
etcdctl put foo1 bar1 --lease=694d8431bf497c0b
读取一个key
用户可以从一个etcd集群读取一个key或一个范围内的key,假设集群内有如下键值对:
foo1 bar1
foo2 bar2
foo3 bar3
foo4 bar4
读取foo1:
etcdctl get foo1
如果只需要打印value值,则加上选项“--print-value-only”,具体命令如下所示:
可使用如下命令读取一个范围内的key:
etcdctl get foo foo3 --print-value-only
注意:上述命令所用到的范围是一个半开区间(左闭右开 [foo, foo3))
遍历所有以foo为前缀的key:
etcdctl get --prefix foo
如果要限制输出结果的数量,可使用"--limit"参数:
etcdctl get --prefix foo --limit 2
读取老版本的key
对etcd后端存储的每次修改都会增加etcd集群全局的版本号(reversion),所以只需要提供指定的版本号就能读取相应版本的key:
etcdctl get --prefix foo --rev=6
etcdctl get --prefix foo --rev=7
按key的字段序来读取
当客户端希望读取大于等于key的字节值时,可以使用“--from-key”参数来实现:
假设etcd中已存在如下键值对:
a 123
b 456
c 789
以下命令将读取字典序比b大的所有key:
etcdctl get --from-key b
删除key
用户可以删除etcd集群中的一个key或者一个范围内的key:
删除一个key:返回删除key的个数
etcdctl del a
删除一个范围内的key:
etcdctl del foo1 foo9
如果需要删除某个key的同时返回对应的value,则可以使用"--prev-kv"选项:
etcdctl del --prev-kv b
del子命令也支持用“--prefix”参数来删除以某个字符串为前缀的key,使用“--from-key”将删除字典序大于或等于某个字符串的所有key。
key的历史与watch
etcd具有watch观察机制,一旦某个key发生变化,客户端就能感知到变化。
etcdctl watch foo
上图是一个客户端操作key,另一个客户端watch key。
除了可以watch一个key,也可以watch一个范围内的key:
etcdctl watch foo foo9
也可以watch以某个字符串为前缀的key,命令如下:
etcdctl watch --prefix foo
watch 子命令还支持交互模式,使用"-i"选项可以watch多个key,操作如下:
etcdctl watch -i
需要手动输入多个要watch的key。
从某个版本号开始观察
一个应用可能希望得到某个key所有变化的通知,如果他一直与 etcd保持连接则没有问题,但是如果这个应用挂起了。而恰好这个key又发生了变化,那么这个应用会有很大可能性没有及时接收到这个key的更新。为了保证key变化的不丢失,etcd支持客户端能够在任意时刻观察该key的所有变化。
客户端只需要在调用watch的时候指定一个版本号,就可以获取到该key从该版本号起的所有变化信息:
etcdctl watch --rev=2 foo
watch子命令的"--prev-kv"选项指定返回该key修改前最近一个版本的value。
压缩key版本
为了能让客户端能够访问key过去任意版本的value,etcd会一直保存key所有历史版本的value,然而etcd的磁盘空间不能无线膨胀,因此需要为etcd配置压缩key版本号来释放磁盘空间。
具体命令如下:
etcdctl compact 5
etcdctl get --rev=4 foo1
在压缩key版本前,用户需要权衡,因为压缩后的该版本之前所有篇key的value都将不可用。
用户可以通过get一个key(不论存在与否均可以)来获取当前etcd服务端的版本号,具体代码如下:
[root@localhost ~]# etcdctl get key -w json
{"header":{"cluster_id":14841639068965178418,"member_id":10276657743932975437,"revision":21,"raft_term":9}}
通过上述代码得知,当前etcd最新版本号是21.
租约
租约是etcd v3 API的特性。客户端可以为key授予租约(lease)。当一个key绑定一个租约时,它的生命周期便会与该租约的TTL(time-to-live)保持一致。
每个租约都有一个由用户授予的最小TTL值,而租约的实际TTL值至少等于用户授予的TTL值,事实上,它很有可能会大于该值,这一切由etcd决定。
如果某个租约的TTL超时了,那么该租约就会过期而且上面绑定的所有key都会被自动删除。
#创建一个10s的租约
[root@localhost ~]# etcdctl lease grant 10
lease 694d843202d1610a granted with TTL(10s)
#为key绑定租约
[root@localhost ~]# etcdctl put foo bar --lease=694d843202d1610a
OK
撤销租约
客户端既然能够授予租约,也能够撤销租约:
etcdctl lease grant 1000
etcdctl put foo bar --lease=694d843202d1610e
etcdctl get foo
#revoke 撤销租约
etcdctl lease revoke 694d843202d1610e
etcdctl get foo
租约被撤销后,将会删除绑定在上面的所有key。
续租
客户端也能通过刷新TTL的方式为租约续租,使它不过期。
命令如下:
etcdctl lease keep-alive 694d843202d16114
如上图所示,每次续租都发生在该租约快过期的时候,且续租的TTL等于最初授予的值。
获取租约信息
假设已经完成了如下操作:
etcdctl lease grant 1000
etcdctl put foo bar --lease=694d843202d16117
etcdctl put foo2 bar2 --lease=694d843202d16117
以下命令将返回租约的TTL以及剩余时间::
etcdctl lease timetolive 694d843202d16117
使用"--keys"选项能够输出其上绑定的keys,具体命令如下所示:
etcdctl lease timetolive --keys 694d843202d16117
如果租约不存在或者已经过期,将会返回: