ETCD etcdctl：客户端操作 etcd 服务端的工具

安装好 etcd 后，我们将开始体验如何使用 etcd。这一讲，我将会基于 etcd 自带的客户端工具——etcdctl 来演示 etcd 常用的一些操作，帮助你快速入手 etcd。

 

etcdctl 客户端

---

etcdctl 是一个命令行客户端，便于我们进行服务测试或手动修改数据库内容，我们刚开始熟悉 etcd 功能时可以通过 etdctl 客户端熟悉相关操作。etcdctl 在两个不同的 etcd 版本（v2 和 v3）下的功能和使用方式也完全不同。一般通过如下方式来指定使用 etcd 的版本：

export ETCDCTL_API=2
export ETCDCTL_API=3

主要讲解 API 3。etcd 项目二进制发行包中已经包含了 etcdctl 工具，通过 etcd 安装包中的 etcdctl 可执行文件可以进行调用。下面我们先来看看 etcd 的常用命令有哪些，并进行实践应用。

 

常用命令介绍

---

我们首先来看下 etcdctl 支持哪些命令，通过etcdctl -h命令查看：

$ etcdctl -h

NAME:

  etcdctl - A simple command line client for etcd3.

USAGE:

  etcdctl [flags]

VERSION:

  3.4.4

API VERSION:

  3.4

COMMANDS:

OPTIONS:

etcdctl 支持的命令大体上分为数据库操作和非数据库操作两类。其中数据库的操作命令是最常用的命令，我们将在下面具体介绍。其他的命令如用户、角色、授权、认证相关，你可以根据语法自己尝试一下。

 

数据库操作

---

数据库操作基本围绕着对键值和目录的 CRUD 操作（即增删改查），及其对应的生命周期管理。我们上手这些操作其实很方便，因为这些操作是符合 REST 风格的一套 API 操作。

etcd 在键的组织上采用了类似文件系统中目录的概念，即层次化的空间结构，我们指定的键可以作为键名，如：testkey，实际上，此时键值对放于根目录 / 下面。我们也可以为键的存储指定目录结构，如 /cluster/node/key；如果不存在 /cluster/node 目录，则 etcd Server 将会创建相应的目录结构。

下面我们基于键操作、watch、lease 三类分别介绍 etcdctl 的使用与实践。

 

键操作

---

键操作包括最常用的增删改查操作，包括 PUT、GET、DELETE 等命令。

PUT 设置或者更新某个键的值。例如：

$ etcdctl put /test/foo1 "Hello world"
$ etcdctl put /test/foo2 "Hello world2"
$ etcdctl put /test/foo3 "Hello world3"

成功写入三对键值，/test/foo1、/test/foo2 和 /test/foo3。

GET 获取指定键的值。例如获取 /testdir/testkey 对应的值：

$ etcdctl get /testdir/testkey
Hello world

除此之外， etcdctl 的 GET 命令还提供了根据指定的键（key），获取其对应的十六进制格式值，即以十六进制格式返回：

$ etcdctl get /test/foo1 --hex
\x2f\x74\x65\x73\x74\x64\x69\x72\x2f\x74\x65\x73\x74\x6b\x65\x79 #键
\x48\x65\x6c\x6c\x6f\x20\x77\x6f\x72\x6c\x64 #值

加上​​--print-value-only​​可以读取对应的值。十六进制在 etcd 中有多处使用，如租约 ID也是十六进制。

GET 范围内的值：

$ etcdctl get /test/foo1 /test/foo3
/test/foo1
Hello world
/test/foo2
Hello world2

可以看到，上述操作获取了大于等于 /test/foo1，且小于 /test/foo3 的键值对。foo3 不在范围之内，因为范围是半开区间 [foo1, foo3)，不包含 foo3。

获取某个前缀的所有键值对，通过 --prefix 可以指定前缀：

$ etcdctl get --prefix /test/foo
/test/foo1
Hello world
/test/foo2
Hello world2
/test/foo3
Hello world3

这样就能获取所有以 /test/foo 开头的键值对，当前缀获取的结果过多时，还可以通过 --limit=2 限制获取的数量：

etcdctl get --prefix --limit=2 /test/foo

读取键过往版本的值，应用可能想读取键的被替代的值。

例如，应用可能想通过访问键的过往版本回滚到旧的配置。或者，应用可能想通过多个请求得到一个覆盖多个键的统一视图，而这些请求可以通过访问键历史记录而来。因为 etcd 集群上键值存储的每个修改都会增加 etcd 集群的全局修订版本，应用可以通过提供旧有的 etcd 修改版本来读取被替代的键。现有如下键值对：

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

以下是访问以前版本 key 的示例：

$ etcdctl get --prefix foo # 访问最新版本的 key
foo
bar_new
foo1
bar1_new
$ etcdctl get --prefix --rev=4 foo # 访问第 4 个版本的 key
foo
bar_new
foo1
bar1
$ etcdctl get --prefix --rev=3 foo #  访问第 3 个版本的 key
foo
bar
foo1
bar1
$ etcdctl get --prefix --rev=2 foo #  访问第 3 个版本的 key
foo
bar
$ etcdctl get --prefix --rev=1 foo #  访问第 1 个版本的 key

应用可能想读取大于等于指定键的 byte 值的键。假设 etcd 集群已经有如下列键：

a = 123
b = 456
z = 789

读取大于等于键 b 的 byte 值的键的命令：

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