ETCD:与etcd进行交互

原文地址：Interacting with etcd

与etcd进行交互

用户更多的是经过putting或者是getting从etcd获取一个键对应的值。这一部分描述了如何经过etcdctl作这些工做。etcdctl是一个与etcd服务器进行交互的命令行工具.这里的描述适用于gRPC APIs或者是客户端库的APIs。
用于与etcd交互的API版本能够经过环境变量ETCDCTL_API设置为2或者3.默认状况下，分支为(3.4)的主版本使用V3 的API，而早期的版本(3.3或者更早)默认使用V2 API。
注意使用V2 API所建立的任何Key不可以经过V3 API进行访问。而V3 API etcdctl get获取V2 的Key将返回0并退出，这是预料之中的状况。

export ETCDCTL_API=3

发现版本

使用合适的命令在执行不一样版本的etcd时etcdctl和服务器API的版本将会有用。
这里的命令可用于发现版本信息：

$ etcdctl version
etcdctl version:3.1.0-alpha.0+git
API version:3.1

写入一个KEY

应用程序经过向etcd集群写入Keys来存储Keys，每次存储的Key将会经过Raft协议实现一致性与可扩展性复制到全部的etcd集群成员中。
这里的命令是将Keyfoo的值存储到bar上：

$ etcdctl put foo bar
OK

给Key附上一个租约，Key将在一个具体的时间间隔被设置。
这里的命令是在10秒后将Keyfoo的值存储到bar上：

$ etcdctl put foo1 bar1 --lease=1234abcd

注意：以上命令中租约ID为1234abcd将会在租约建立10秒后将id返回，这个id将附在Key上。

读取Keys

应用程序能够从一个etcd集群中读取Key，可能会查询到单个Key，或者是一个范围内的Key。
好比etcd集群中存储如下Key：

foo = bar
foo1 = bar1
foo2 = bar2
foo3 = bar3

这里的命令是读取Keyfoo对应的值：

$ etcdctl get foo
foo
bar

这里的命令是读取Keyfoo对应的十六进制的值:

$ etcdctl get foo --hex
\x66\x6f\x6f       #Key
\x62\x61\x72       #Value

这里的命令是只读取Keyfoo对应的值：

$ etcdctl get foo --print-value-only
bar

这里的命令是读取从Keyfoo到Keyfoo3范围内对应的值：

$ etcdctl get foo foo3
foo
bar
foo1
bar1
foo2
bar2

注意这里Key为foo3不包括在内由于这里的范围是半开区间[foo,foo3)，不包括foo3。

这里的命令是获取前缀为foo的Key的范围内全部的值：

$ etcdctl get --prefix foo
foo
bar
foo1
bar1
foo2
bar2
foo3
bar3

这里的命令是获取前缀为foo的Key的范围内全部的值,而且限制结果集为2：

$ etcdctl get --prefix --limit=2 foo
foo
bar
foo1
bar1

读取以前版本的Keys：

应用程度可能但愿读取一个被替代的版本的Key。例如，一个应用程序可能想要经过读取一个先前版本的Key来回滚到一个老的配置。另外，一个应用程序可能想要经过访问Key的历史记录对多个Key经过多个请求获取一致性的结果。因为对etcd集群中键值对的每一次修改都会增长对在etcd集群中的全局修订存储，应用程序能够经过提供一个老的版原本读取被替代的Keys。
好比一个etcd集群中存在如下的Keys：

foo = bar         # revision = 2
foo1 = bar1       # revision = 3
foo = bar_new     # revision = 4
foo1 = bar1_new   # revision = 5

这里的例子是访问过去版本的Keys：

$ 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

读取大于或等于一个具体的Key的比特值的Key：

应用程序可能想要读取大于或等于一个具体的Key的byte值的Key。
一个etcd集群中有如下的Keys：

a = 123
b = 456
z = 789

这里的命令是读取大于或等于Key b的byte值的Key：

$ etcdctl get --from-key b
b
456
z
789

删除 Keys

应用程序能够从etcd集群中删除一个Key或者删除一个范围内的Key：
一个etcd集群中有如下的Keys：

foo = bar
foo1 = bar1
foo3 = bar3
zoo = val
zoo1 = val1
zoo2 = val2
a = 123
b = 456
z = 789

这里的命令是删除Keyfoo:

$ etcdctl del foo
1 # 1 个 key 被删除

这里的命令是删除从Keyfoo到Keyfoo9范围内的Key:

$ etcdctl del foo foo9
2 # 2 个 keys 被删除

这里的命令是删除Keyzoo并将已删除的键值对返回:

$ etcdctl del --prev-kv zoo
1   # 1 个 key 被删除
zoo # 被删除的Key
val # 被删除的Key所对应的Value

这里的命令是删除前缀为zoo的Keys:

$ etcdctl del --prefix zoo
2 # 2 个 key 被删除

这里的命令是读取大于或等于Key b的byte值的Keys：

$ etcdctl del --from-key b
2 # 2 个 key 被删除

观察key的变化

应用程序能够监视一个Key或者一个范围内的Keys的每一次更新。
这里的命令是观察keyfoo:

$ etcdctl watch foo
# 在另外一个终端执行: etcdctl put foo bar
PUT
foo
bar

这里的命令是观察十六进制的keyfoo:

$ etcdctl watch foo --hex
# 在另外一个终端执行: etcdctl put foo bar
PUT
\x66\x6f\x6f          # Key
\x62\x61\x72          # Value

这里的命令是观察从Keyfoo到Keyfoo9范围内的Key：

$ etcdctl watch foo foo9
# 在另外一个终端执行: etcdctl put foo bar
PUT
foo
bar
# 在另外一个终端执行: etcdctl put foo1 bar1
PUT
foo1
bar1

这里的命令是观察前缀为foo的Key的范围内全部的值：

$ etcdctl watch --prefix foo
# 在另外一个终端执行: etcdctl put foo bar
PUT
foo
bar
# 在另外一个终端执行: etcdctl put fooz1 barz1
PUT
fooz1
barz1

这里的命令是观察多个Keysfoo和zoo:

$ etcdctl watch -i
$ watch foo
$ watch zoo
# 在另外一个终端执行: etcdctl put foo bar
PUT
foo
bar
# 在另外一个终端执行: etcdctl put zoo val
PUT
zoo
val

观察Keys的历史版本

应用程序可能想要观察etcd中Keys的更新历史。例如，应用程序可能想获取key的全部修改；若是应用程序保持与etcd的链接，那么命令watch已经足够。然而，若是应用程序或者etcd宕机，一次更新可能就会失败，应用程序可能不能实时接收Key的更新。为了保证更新能够被交付，应用程序必须经过观察到Keys的历史更新。为了作到这些，应用程序要指定观察的历史版本，就像读取历史版本的Keys：
咱们首先完成如下操做：

$ 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
# 在另外一个终端执行 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

观察进度

应用程序可能想要检查观察者进度以肯定最新的观察者流的状态。例如，若是观察者更新的缓存，那么就能够经过原子读取与修改进度进行比较知道缓存内容是否已通过时。
进度请求能够经过progress命令与观察者session进行交互在一个观察者流中告诉服务器发送一个进度提示更新.

$ etcdctl watch -i
$ watch a
$ progress
progress notify: 1
# 在另外一个终端执行: etcdctl put x 0
# 在另外一个终端执行: etcdctl put y 1
$ progress
progress notify: 3

注意，在进度提示响应中的修改号来自观察者流链接到的本地etcd服务器。若是该节点被分区而且不是该分区的一部分，这个进度提示修改版本可能会低于由未分区的etcd服务器节点返回的修改版本。

压缩修改

正如咱们提到的，etcd保持修改信息因此应用能够读取过去版本的Keys，然而，为了不无数的修改历史累积，对过去的修改进行压缩是很重要的。在压缩后，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

注意：etcd服务器的当前版本可使用json格式的命令经过(存在或不存在的)key发现。例以下面的经过查看在etcd服务器中不存在的myKey:

$ etcdctl get mykey -w=json
{"header":{"cluster_id":14841639068965178418,"member_id":10276657743932975437,"revision":15,"raft_term":4}}

授予租约

应用程序能够为etcd集群上的Keys授予一个租约。当Key附上租约后，它的生命周期会绑定到租约的生命周期并由存活时间(TTL)进行管理。每个租约都有一个由应用程序授予的最小的TTL值.这个租约实际的TTL值至少是最小的TTL值，由etcd集群决定。一旦超过租约的TTL，租约将会超时并删除附上的全部的Keys。
这里有命令授予一个租约：

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

# attach key foo to lease 32695410dcc0ca06
$ etcdctl put --lease=32695410dcc0ca06 foo bar
OK

撤销租约

应用程序能够根据租约ID撤销租约，撤销一个租约将删除附上的全部的Keys。
例如咱们完成下面的操做：

$ etcdctl lease grant 60
lease 32695410dcc0ca06 granted with TTL(60s)
$ 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 60
lease 32695410dcc0ca06 granted with TTL(60s)

这里有命令保持租约存活：

$ etcdctl lease keep-alive 32695410dcc0ca06
lease 32695410dcc0ca06 keepalived with TTL(60)
lease 32695410dcc0ca06 keepalived with TTL(60)
lease 32695410dcc0ca06 keepalived with TTL(60)
...

获取租约信息

应用程序可能想知道关于租约的信息，因此能够经过从新建立或者检查租约是否仍然生存或已经超时。应用程序可能也想知道一个具体的租约上所附的Key。
例如咱们完成下面的操做：

# 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)

这里有命令获取租约上所依附的关于Keys的信息：

$ 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