etcd使用教程[1]

与etcd交互

本文翻译自官方文档：https://coreos.com/etcd/docs/latest/dev-guide/interacting_v3.html

用户主要通过输入或获取**的值与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上述命令中的租约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

以下是只读取**值的命令foo：

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

这里是命令范围从键foo到oo3：

$ 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

这里是读取大于或等于键的字节值的键的命令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

以下是删除大于或等于键的字节值的键的命令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

注意：当前的etcd服务器修订版可以使用json格式的任何键（存在或不存在）上的get命令找到。下面的例子显示了在etcd服务器中不存在的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(10)
lease 32695410dcc0ca06 keepalived with TTL(10)
lease 32695410dcc0ca06 keepalived with TTL(10)
...

获取租赁信息

应用程序可能想要了解租赁信息，以便它们可以续订或检查租赁是否仍然存在或已过期。应用程序也可能想知道特定租约所附的**。

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

# 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