与etcd交互

与etcd交互
用户通常通过放置或获取密钥的值来与etcd交互。本节介绍如何使用etcdctl这一命令行工具与etcd服务器进行交互。此处描述的概念应适用于gRPC API或客户端库API。

默认情况下，etcdctl使用v2 API与etcd服务器通信以实现向后兼容。要使etcdctl使用v3 API与etcd对话，必须通过ETCDCTL_API环境变量将API版本设置为版本3 。

export ETCDCTL_API=3
查找版本
etcdctl版本和Server API版本可用于查找用于在etcd上执行各种操作的相应命令。

以下是查找版本的命令：

$ etcdctl version
etcdctl version: 3.1.0-alpha.0+git
API version: 3.1
写一把钥匙
应用程序通过写入密钥将密钥存储到etcd集群中。每个存储的密钥都通过Raft协议复制到所有etcd集群成员，以实现一致性和可靠性。

这里是设置键的值的命令foo到bar：

$ etcdctl put foo bar
OK
还可以通过将租约附加到指定的时间间隔来设置密钥。

这里是设置键的值的命令foo1，以bar110秒。

$ etcdctl put foo1 bar1 --lease=1234abcd
OK
注意：1234abcd上述命令中的lease id 是指创建10s租约时返回的id。然后可以将此ID附加到密钥。

读键
应用程序可以从etcd集群中读取密钥的值。查询可以读取单个键或一系列键。

假设etcd集群已存储以下密钥：

foo = bar
foo1 = bar1
foo2 = bar2
foo3 = bar3
这是读取键值的命令foo：

$ etcdctl get foo
foo
bar
以下是以foo十六进制格式读取键值的命令：

$ etcdctl get foo --hex
\x66\x6f\x6f # Key
\x62\x61\x72 # Value
以下是只读取key值的命令foo：

$ etcdctl get foo --print-value-only
bar
这里是命令从范围的钥匙foo到foo3：

$ etcdctl get foo foo3
foo
bar
foo1
bar1
foo2
bar2
请注意，foo3排除因为范围超过半开区间[foo, foo3)而不包括在内foo3。

以下是对所有以前缀为前缀的键的范围命令foo：

$ etcdctl get --prefix foo
foo
bar
foo1
bar1
foo2
bar2
foo3
bar3
以下是对所有前缀的键进行范围调整的命令foo，将结果数限制为2：

$ etcdctl get --prefix --limit=2 foo
foo
bar
foo1
bar1
阅读过去的密钥版本
应用程序可能希望读取密钥的已取代版本。例如，应用程序可能希望通过访问密钥的早期版本来回滚到旧配置。或者，通过访问密钥历史，应用程序可能希望通过多个请求在多个密钥上进行一致的查看。由于对etcd集群键值存储的每次修改都会增加etcd集群的全局修订，因此应用程序可以通过提供旧的etcd修订来读取取代的键。

假设一个etcd集群已经有以下密钥：

foo = bar # revision = 2
foo1 = bar1 # revision = 3
foo = bar_new # revision = 4
foo1 = bar1_new # revision = 5
以下是访问过去版本密钥的示例：

$ etcdctl get --prefix foo # access the most recent versions of keys
foo
bar_new
foo1
bar1_new

$ etcdctl get --prefix --rev=4 foo # access the versions of keys at revision 4
foo
bar_new
foo1
bar1

$ etcdctl get --prefix --rev=3 foo # access the versions of keys at revision 3
foo
bar
foo1
bar1

$ etcdctl get --prefix --rev=2 foo # access the versions of keys at revision 2
foo
bar

$ etcdctl get --prefix --rev=1 foo # access the versions of keys at revision 1
读取大于或等于指定键字节值的键
应用程序可能希望读取大于或等于指定键的字节值的键。

假设一个etcd集群已经有以下密钥：

a = 123
b = 456
z = 789
以下是读取大于或等于key的字节值的键的命令b：

$ etcdctl get --from-key b
b
456
z
789
删除键
应用程序可以从etcd集群中删除密钥或一系列密钥。

假设一个etcd集群已经有以下密钥：

foo = bar
foo1 = bar1
foo3 = bar3
zoo = val
zoo1 = val1
zoo2 = val2
a = 123
b = 456
z = 789
这是删除键的命令foo：

$ etcdctl del foo
1 # one key is deleted
这里是删除键，从命令foo到foo9：

$ etcdctl del foo foo9
2 # two keys are deleted
以下是zoo使用已返回的已删除键值对删除键的命令：

$ etcdctl del --prev-kv zoo
1 # one key is deleted
zoo # deleted key
val # the value of the deleted key
以下是删除具有前缀的键的命令zoo：

$ etcdctl del --prefix zoo
2 # two keys are deleted
这是删除大于或等于key的字节值的键的命令b：

$ etcdctl del --from-key b
2 # two keys are deleted
观看关键变化
应用程序可以监视密钥或一系列密钥，以监控任何更新。

这是在密钥上观察的命令foo：

$ etcdctl watch foo
#in another terminal: etcdctl put foo bar
PUT
foo
bar
以下是以foo十六进制格式监视密钥的命令：

$ etcdctl watch foo --hex
#in another terminal: etcdctl put foo bar
PUT
\x66\x6f\x6f # Key
\x62\x61\x72 # Value
这里是上观看从一系列关键的命令foo来foo9：

$ etcdctl watch foo foo9
#in another terminal: etcdctl put foo bar
PUT
foo
bar
#in another terminal: etcdctl put foo1 bar1
PUT
foo1
bar1
这是监视具有前缀的键的命令foo：

$ etcdctl watch --prefix foo
#in another terminal: etcdctl put foo bar
PUT
foo
bar
#in another terminal: etcdctl put fooz1 barz1
PUT
fooz1
barz1
这里是观看多个按键的命令foo和zoo：

$ etcdctl watch -i
$ watch foo
$ watch zoo
#in another terminal: etcdctl put foo bar
PUT
foo
bar
#in another terminal: etcdctl put zoo val
PUT
zoo
val
观察钥匙的历史变化
应用程序可能希望监视etcd中密钥的历史更改。例如，应用程序可能希望接收密钥的所有修改; 如果应用程序保持连接到etcd，那么watch就足够了。但是，如果应用程序或etcd失败，则在失败期间可能会发生更改，并且应用程序将不会实时接收更新。为确保提供更新，应用程序必须能够监视密钥的历史更改。为此，应用程序可以在手表上指定历史版本，就像读取过去版本的键一样。

假设我们完成了以下操作序列：

$ etcdctl put foo bar # revision = 2
OK
$ etcdctl put foo1 bar1 # revision = 3
OK
$ etcdctl put foo bar_new # revision = 4
OK
$ etcdctl put foo1 bar1_new # revision = 5
OK
以下是观察历史变化的示例：

#watch for changes on key foo since revision 2
$ etcdctl watch --rev=2 foo
PUT
foo
bar
PUT
foo
bar_new
#watch for changes on key foo since revision 3
$ etcdctl watch --rev=3 foo
PUT
foo
bar_new
以下是仅从最近的历史变化中观看的示例：

#watch for changes on key foo and return last revision value along with modified value
$ etcdctl watch --prev-kv foo
#in another terminal: etcdctl put foo bar_latest
PUT
foo # key
bar_new # last value of foo key before modification
foo # key
bar_latest # value of foo key after modification
压缩修订版
正如我们所提到的，etcd会保留修订版，以便应用程序可以读取过去版本的密钥。但是，为了避免累积无限量的历史记录，重要的是要压缩过去的修订版。压缩后，etcd删除了历史修订，释放资源以备将来使用。在压缩修订版之前修改的所有被取代数据都将不可用。

这是压缩修订版的命令：

$ etcdctl compact 5
compacted revision 5

#any revisions before the compacted one are not accessible
$ etcdctl get --rev=4 foo
Error: rpc error: code = 11 desc = etcdserver: mvcc: required revision has been compacted
注意：可以使用json格式的任何密钥（存在或不存在）上的get命令找到etcd服务器的当前版本。示例如下所示，mykey服务器中不存在mykey：

$ etcdctl get mykey -w=json
{“header”:{“cluster_id”:14841639068965178418,“member_id”:10276657743932975437,“revision”:15,“raft_term”:4}}
授予租约
应用程序可以为来自etcd集群的密钥授予租约。当密钥附加到租约时，其生命周期与租约的生命周期相关，而租约的生命周期又由生存时间（TTL）控制。每个租约都有一个应用程序在授权时指定的最小生存时间（TTL）值。租约的实际TTL值至少是最小TTL，由etcd集群选择。一旦租约的TTL过去，租约就会到期，所有附加的密钥都会被删除。

这是授予租约的命令：

#grant a lease with 10 second TTL
$ etcdctl lease grant 10
lease 32695410dcc0ca06 granted with TTL(10s)

#attach key foo to lease 32695410dcc0ca06
$ etcdctl put --lease=32695410dcc0ca06 foo bar
OK
撤销租约
申请通过租赁ID撤销租约。撤消租约会删除所有附加的密钥。

假设我们完成了以下操作序列：

$ etcdctl lease grant 10
lease 32695410dcc0ca06 granted with TTL(10s)
$ etcdctl put --lease=32695410dcc0ca06 foo bar
OK
以下是撤销同一租约的命令：

$ etcdctl lease revoke 32695410dcc0ca06
lease 32695410dcc0ca06 revoked

$ etcdctl get foo
#empty response since foo is deleted due to lease revocation
让租约保持活力
应用程序可以通过刷新其TTL来保持租约活跃，因此它不会过期。

假设我们完成了以下操作序列：

$ etcdctl lease grant 10
lease 32695410dcc0ca06 granted with TTL(10s)
这是保持相同租约存活的命令：

$ etcdctl lease keep-alive 32695410dcc0ca06
lease 32695410dcc0ca06 keepalived with TTL(100)
lease 32695410dcc0ca06 keepalived with TTL(100)
lease 32695410dcc0ca06 keepalived with TTL(100)
…
获取租赁信息
应用程序可能希望了解租赁信息，以便可以续订或检查租约是否仍然存在或已过期。应用程序可能还想知道附加特定租约的密钥。

假设我们完成了以下操作序列：

#grant a lease with 500 second TTL
$ etcdctl lease grant 500
lease 694d5765fc71500b granted with TTL(500s)

#attach key zoo1 to lease 694d5765fc71500b
$ etcdctl put zoo1 val1 --lease=694d5765fc71500b
OK

#attach key zoo2 to lease 694d5765fc71500b
$ etcdctl put zoo2 val2 --lease=694d5765fc71500b
OK
以下是获取租赁信息的命令：

$ etcdctl lease timetolive 694d5765fc71500b
lease 694d5765fc71500b granted with TTL(500s), remaining(258s)
以下是获取租约信息以及租约附带的密钥的命令：

$ etcdctl lease timetolive --keys 694d5765fc71500b
lease 694d5765fc71500b granted with TTL(500s), remaining(132s), attached keys([zoo2 zoo1])

#if the lease has expired or does not exist it will give the below response:
Error: etcdserver: requested lease not found