开发指南

• 1: 发现服务协议
• 2: 配置本地集群
• 3: 与 etcd 交互
• 4: 为什么使用 gRPC 网关
• 5: gRPC 命名与发现
• 6: 将 etcd 集成到 Go 应用中
• 7: 系统限制
• 8: etcd 功能
• 9: API 参考
• 10: API 参考：并发

1 - 发现服务协议

发现服务协议有助于新 etcd 成员在集群引导阶段通过共享的发现 URL 发现集群中的所有其他成员。

发现服务协议仅在集群引导阶段使用，不可用于运行时重配置或集群监控。

该协议使用新的发现令牌来引导一个唯一的 etcd 集群。请注意，一个发现令牌只能代表一个 etcd 集群。只要该令牌的发现协议已启动，即使中途失败，也不得用于引导另一个 etcd 集群。

本文其余部分将通过示例介绍发现过程，这些示例对应自托管发现集群。公共发现服务 discovery.etcd.io 的工作方式相同，但增加了一层优化，用于抽象掉难看的 URL，自动生成 UUID，并对过多请求提供一定防护。其核心仍使用 etcd 集群作为数据存储系统，如本文所述。

协议工作流

发现协议的核心思想是利用一个内部 etcd 集群来协调新集群的引导过程。首先，所有新成员与发现服务交互，协助生成预期的成员列表。随后，每个新成员使用该列表引导其服务器，这一操作实现的功能与 -initial-cluster 标志相同。

在以下示例工作流程中，我们将以 curl 格式列出协议的每一步，以便于理解。

按照惯例，etcd 发现协议使用键前缀 _etcd/registry。若 http://example.com 托管用于发现服务的 etcd 集群，则发现键空间的完整 URL 将为 http://example.com/v2/keys/_etcd/registry。本示例中将使用该 URL 前缀。

创建新的发现令牌

生成一个唯一令牌，用于标识新集群。该令牌将在后续步骤中作为发现键空间的唯一前缀使用。一种简便的方法是使用 uuidgen：

UUID=$(uuidgen)

指定预期集群规模

发现令牌需要指定集群大小，该大小必须明确提供。发现服务使用此大小来判断是否已找到将初始组成集群的所有成员。

curl -X PUT http://example.com/v2/keys/_etcd/registry/${UUID}/_config/size -d value=${cluster_size}

通常，集群大小为 3、5 或 7。请参阅 optimal cluster size 以获取更多详细信息。

启动 etcd 进程

给定发现 URL 后，将其作为 -discovery 标志使用，并启动 etcd 进程。每个 etcd 进程在接收到 -discovery 标志时，将自动执行以下内部步骤。

自我注册

etcd 进程的首要任务是将自身作为成员注册到发现 URL。这是通过在发现 URL 中以成员 ID 作为键来创建实现的。

curl -X PUT http://example.com/v2/keys/_etcd/registry/${UUID}/${member_id}?prevExist=false -d value="${member_name}=${member_peer_url_1}&${member_name}=${member_peer_url_2}"

检查状态

它检查发现 URL 中预期的集群大小和注册状态，并据此决定下一步操作。

curl -X GET http://example.com/v2/keys/_etcd/registry/${UUID}/_config/size
curl -X GET http://example.com/v2/keys/_etcd/registry/${UUID}

如果已注册的成员仍不足，将等待缺失的成员出现。

如果注册的成员数量大于预期的集群大小 N，则将前 N 个注册的成员视为集群的成员列表。如果该成员自身在成员列表中，发现过程成功，并通过成员列表获取所有对等成员。如果不在成员列表中，发现过程将以集群已满的失败状态结束。

在 etcd 实现中，成员可能在注册自身之前就检查集群状态。因此，如果集群已满，该成员可能会快速失败。

等待所有成员就位

等待过程在 etcd API 文档 中有详细描述。

curl -X GET http://example.com/v2/keys/_etcd/registry/${UUID}?wait=true&waitIndex=${current_etcd_index}

它将持续等待，直到找到所有成员。

公共发现服务

CoreOS Inc. 在 https://discovery.etcd.io/ 提供公开的发现服务，该服务具备多项便捷功能，便于使用。

隐藏键前缀

公共发现服务将 https://discovery.etcd.io/${UUID} 重定向至 /v2/keys/_etcd/registry 处的 etcd 集群。该服务可隐藏注册键前缀，使发现 URL 更短且更易读。

获取新令牌

GET /new

Sent query:
	size=${cluster_size}
Possible status codes:
	200 OK
	400 Bad Request
200 Body:
	generated discovery url

服务中的生成过程遵循从 创建新的发现令牌 到 指定预期集群大小 的步骤。

检查发现状态

GET /${UUID}

可通过请求 UUID 的值来检查此发现令牌的状态，包括已注册的机器。

开源代码库

仓库位于 https://github.com/coreos/discovery.etcd.io .，可用于构建自定义发现服务。

2 - 配置本地集群

对于测试和开发部署，最快捷简便的方式是配置本地集群。对于生产部署，请参考 clustering 章节。

本地独立集群

启动集群

运行以下命令以将 etcd 集群部署为独立集群：

$ ./etcd
...

如果 etcd 二进制文件不在当前工作目录中，它可能位于 $GOPATH/bin/etcd 或 /usr/local/bin/etcd。请相应地运行命令。

运行中的 etcd 成员在 localhost:2379 上监听客户端请求。

与集群交互

使用 etcdctl 与运行中的集群交互：

1. 在集群中存储一个示例键值对：

     $ ./etcdctl put foo bar
     OK

   如果输出 OK，表示键值对已成功存储。

2. 获取 foo 的值：

   $ ./etcdctl get foo
   bar

   如果返回 bar，表示可正常与 etcd 集群交互。

本地多成员集群

启动集群

在 etcd 代码仓库根目录下提供了一个 Procfile，用于便捷地配置本地多成员集群。要启动多成员集群，请进入 etcd 源码根目录并执行以下操作：

1. 安装 goreman 以控制基于 Procfile 的应用程序：

   $ go install github.com/mattn/goreman@latest

2. 使用 goreman 和 etcd 的默认 Procfile 启动集群：

   $ goreman -f Procfile start

   各成员启动后，分别在 localhost:2379、localhost:22379 和 localhost:32379 上监听客户端请求。

与集群交互

使用 etcdctl 与运行中的集群交互：

1. 打印成员列表：

   $ etcdctl --write-out=table --endpoints=localhost:2379 member list

   etcd 成员列表如下：

   +------------------+---------+--------+------------------------+------------------------+
   |        ID        | STATUS  |  NAME  |       PEER ADDRS       |      CLIENT ADDRS      |
   +------------------+---------+--------+------------------------+------------------------+
   | 8211f1d0f64f3269 | started | infra1 | http://127.0.0.1:2380  | http://127.0.0.1:2379  |
   | 91bc3c398fb3c146 | started | infra2 | http://127.0.0.1:22380 | http://127.0.0.1:22379 |
   | fd422379fda50e48 | started | infra3 | http://127.0.0.1:32380 | http://127.0.0.1:32379 |
   +------------------+---------+--------+------------------------+------------------------+

2. 在集群中存储一个示例键值对：

   $ etcdctl put foo bar
   OK

   如果输出 OK，表示键值对已成功存储。

测试容错能力

为验证 etcd 的容错能力，请终止一个成员，并尝试获取键。

1. 确定待停止成员的进程名称。

   Procfile 列出了多成员集群的属性。以进程名为 etcd2 的成员为例。

2. 停止成员：

   # kill etcd2
   $ goreman run stop etcd2

3. 存储键：

   $ etcdctl put key hello
   OK

4. 检索上一步存储的键：

   $ etcdctl get key
   hello

5. 从已停止的成员中检索键：

   $ etcdctl --endpoints=localhost:22379 get key

   该命令应显示由连接失败引起的错误：

   2017/06/18 23:07:35 grpc: Conn.resetTransport failed to create client transport: connection error: desc = "transport: dial tcp 127.0.0.1:22379: getsockopt: connection refused"; Reconnecting to "localhost:22379"
   Error:  grpc: timed out trying to connect

6. 重启已停止的成员：

   $ goreman run restart etcd2

7. 从重启后的成员获取键：

   $ etcdctl --endpoints=localhost:22379 get key
   hello

   重启成员后会重新建立连接，etcdctl 现在应能成功获取该键。如需详细了解如何与 etcd 交互，请参阅与 etcd 交互 。

3 - 与 etcd 交互

用户通常通过设置或获取键的值来与 etcd 交互。本节介绍如何使用 etcdctl（用于与 etcd 服务器交互的命令行工具）实现这一操作。此处描述的概念同样适用于 gRPC API 或客户端库 API。

etcdctl 与 etcd 通信时所使用的 API 版本可通过 ETCDCTL_API 环境变量设置为 2 或 3。默认情况下，主分支（3.4）上的 etcdctl 使用 v3 API，而较早版本（3.3 及更早）默认使用 v2 API。

请注意，使用 v2 API 创建的任何键均无法通过 v3 API 查询。对 v2 键执行 v3 API etcdctl get 操作时，将返回 0 且不包含键数据，这是预期行为。

export ETCDCTL_API=3

查找版本

etcdctl 版本与服务器 API 版本可用于确定执行 etcd 各项操作时应使用的正确命令。

以下是查找版本号的命令：

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

写入键

应用程序通过向键写入数据将键存储到 etcd 集群中。每个存储的键都会通过 Raft 协议复制到集群中的所有成员，以实现一致性和可靠性。

以下是将键 foo 的值设置为 bar 的命令：

$ etcdctl put foo bar
OK

此外，可通过为键附加租约，将其设置为指定时间间隔。

以下是将键 foo1 的值设置为 bar1 并保留 10 秒的命令。

$ etcdctl put foo1 bar1 --lease=1234abcd
OK

读取键

应用程序可从 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 到 foo3 范围内键的命令：

$ etcdctl get foo foo3
foo
bar
foo1
bar1
foo2
bar2

以下是遍历所有以 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

以下是使用 RangeStream RPC 遍历所有以 foo 为前缀的键的命令。结果与单次 Range 调用完全相同：

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

--stream 不支持 --order、--sort-by 或修订版本过滤。

读取键的过往版本

应用程序可能需要读取已被覆盖的键的旧版本。例如，应用程序可通过访问键的早期版本来回滚至旧配置。或者，应用程序可通过访问键的历史记录，在多次请求中获取多个键的一致视图。

由于对 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

监听进度

应用程序可能需要检查监听的进度，以判断监听流的更新状态。例如，若监听用于更新缓存，则了解缓存相对于法定人数读取的修订版本是否过时会很有帮助。

可以使用交互式监听会话中的“progress”命令，向 etcd 服务器请求在监听流中发送进度通知更新：

$ etcdctl watch -i
$ watch a
$ progress
progress notify: 1
# in another terminal: etcdctl put x 0
# in another terminal: etcdctl put y 1
$ progress
progress notify: 3

压缩的修订版本

如前所述，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

$ 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 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 撤销租约。撤销租约将删除其所有关联的键。

假设已完成以下操作序列：

$ 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)
...

获取租约信息

应用程序可能需要了解租约信息，以便能够续期，或检查租约是否仍然有效或已过期。应用程序也可能需要知道某个特定租约所关联的键。

假设已完成以下操作序列：

# 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

4 - 为什么使用 gRPC 网关

etcd v3 使用 gRPC 作为其消息协议。etcd 项目包含一个基于 gRPC 的 Go 客户端 ，以及一个命令行工具 etcdctl ，用于通过 gRPC 与 etcd 集群通信。对于不支持 gRPC 的语言，etcd 提供一个 JSON gRPC 网关 。该网关提供一个 RESTful 代理，可将 HTTP/JSON 请求转换为 gRPC 消息。

使用 gRPC 网关

网关接受 etcd 的 协议缓冲 消息定义的 JSON 映射 。请注意，key 和 value 字段定义为字节数组，因此在 JSON 中必须进行 base64 编码。以下示例使用 curl，但任何 HTTP/JSON 客户端均可正常工作。

备注

自 etcd v3.3 起，gRPC 网关端点已更改：

• etcd v3.2 或更早版本仅使用 [CLIENT-URL]/v3alpha/*。
• etcd v3.3 使用 [CLIENT-URL]/v3beta/*，同时保留 [CLIENT-URL]/v3alpha/*。
• etcd v3.4 使用 [CLIENT-URL]/v3/*，同时保留 [CLIENT-URL]/v3beta/*。
  • [CLIENT-URL]/v3alpha/* 已弃用。
• etcd v3.5 或更高版本仅使用 [CLIENT-URL]/v3/*。
  • [CLIENT-URL]/v3beta/* 已弃用。

gRPC 网关不支持使用 TLS 通用名称进行身份认证。

设置和获取键

使用 /v3/kv/range 和 /v3/kv/put 服务读写键：

<<COMMENT
https://www.base64encode.org/
foo is 'Zm9v' in Base64
bar is 'YmFy'
COMMENT

curl -L http://localhost:2379/v3/kv/put \
  -X POST -d '{"key": "Zm9v", "value": "YmFy"}'
# {"header":{"cluster_id":"12585971608760269493","member_id":"13847567121247652255","revision":"2","raft_term":"3"}}

curl -L http://localhost:2379/v3/kv/range \
  -X POST -d '{"key": "Zm9v"}'
# {"header":{"cluster_id":"12585971608760269493","member_id":"13847567121247652255","revision":"2","raft_term":"3"},"kvs":[{"key":"Zm9v","create_revision":"2","mod_revision":"2","version":"1","value":"YmFy"}],"count":"1"}

# get all keys prefixed with "foo"
curl -L http://localhost:2379/v3/kv/range \
  -X POST -d '{"key": "Zm9v", "range_end": "Zm9w"}'
# {"header":{"cluster_id":"12585971608760269493","member_id":"13847567121247652255","revision":"2","raft_term":"3"},"kvs":[{"key":"Zm9v","create_revision":"2","mod_revision":"2","version":"1","value":"YmFy"}],"count":"1"}

监听键

使用 /v3/watch 服务监听键：

curl -N http://localhost:2379/v3/watch \
  -X POST -d '{"create_request": {"key":"Zm9v"} }' &
# {"result":{"header":{"cluster_id":"12585971608760269493","member_id":"13847567121247652255","revision":"1","raft_term":"2"},"created":true}}

curl -L http://localhost:2379/v3/kv/put \
  -X POST -d '{"key": "Zm9v", "value": "YmFy"}' >/dev/null 2>&1
# {"result":{"header":{"cluster_id":"12585971608760269493","member_id":"13847567121247652255","revision":"2","raft_term":"2"},"events":[{"kv":{"key":"Zm9v","create_revision":"2","mod_revision":"2","version":"1","value":"YmFy"}}]}}

事务

使用 /v3/kv/txn 发起一个事务：

# target CREATE
curl -L http://localhost:2379/v3/kv/txn \
  -X POST \
  -d '{"compare":[{"target":"CREATE","key":"Zm9v","createRevision":"2"}],"success":[{"requestPut":{"key":"Zm9v","value":"YmFy"}}]}'
# {"header":{"cluster_id":"12585971608760269493","member_id":"13847567121247652255","revision":"3","raft_term":"2"},"succeeded":true,"responses":[{"response_put":{"header":{"revision":"3"}}}]}

# target VERSION
curl -L http://localhost:2379/v3/kv/txn \
  -X POST \
  -d '{"compare":[{"version":"4","result":"EQUAL","target":"VERSION","key":"Zm9v"}],"success":[{"requestRange":{"key":"Zm9v"}}]}'
# {"header":{"cluster_id":"14841639068965178418","member_id":"10276657743932975437","revision":"6","raft_term":"3"},"succeeded":true,"responses":[{"response_range":{"header":{"revision":"6"},"kvs":[{"key":"Zm9v","create_revision":"2","mod_revision":"6","version":"4","value":"YmF6"}],"count":"1"}}]}

身份认证

使用 /v3/auth 服务设置身份认证：

# create root user
curl -L http://localhost:2379/v3/auth/user/add \
  -X POST -d '{"name": "root", "password": "pass"}'
# {"header":{"cluster_id":"14841639068965178418","member_id":"10276657743932975437","revision":"1","raft_term":"2"}}

# create root role
curl -L http://localhost:2379/v3/auth/role/add \
  -X POST -d '{"name": "root"}'
# {"header":{"cluster_id":"14841639068965178418","member_id":"10276657743932975437","revision":"1","raft_term":"2"}}

# grant root role
curl -L http://localhost:2379/v3/auth/user/grant \
  -X POST -d '{"user": "root", "role": "root"}'
# {"header":{"cluster_id":"14841639068965178418","member_id":"10276657743932975437","revision":"1","raft_term":"2"}}

# enable auth
curl -L http://localhost:2379/v3/auth/enable -X POST -d '{}'
# {"header":{"cluster_id":"14841639068965178418","member_id":"10276657743932975437","revision":"1","raft_term":"2"}}

使用 /v3/auth/authenticate 对 etcd 进行身份认证以获取身份认证令牌：

# get the auth token for the root user
curl -L http://localhost:2379/v3/auth/authenticate \
  -X POST -d '{"name": "root", "password": "pass"}'
# {"header":{"cluster_id":"14841639068965178418","member_id":"10276657743932975437","revision":"1","raft_term":"2"},"token":"sssvIpwfnLAcWAQH.9"}

将 Authorization 请求头设置为身份认证令牌，以使用身份认证凭据获取键：

curl -L http://localhost:2379/v3/kv/put \
  -H 'Authorization: sssvIpwfnLAcWAQH.9' \
  -X POST -d '{"key": "Zm9v", "value": "YmFy"}'
# {"header":{"cluster_id":"14841639068965178418","member_id":"10276657743932975437","revision":"2","raft_term":"2"}}

错误响应

gRPC 网关将 gRPC 状态转换为 HTTP 状态码和 JSON 错误正文。从 etcd v3.6 开始，升级至 grpc-gateway v2 改变了错误处理方式（参见 v2 迁移指南中的 错误处理说明 ），网关行为现在与 google.rpc.Status（代码、消息、详情）一致，如 Google API 错误模型 所述。历史上，较早版本的 grpc-gateway 也包含一个顶层 error 字段，但该字段在 etcd v3.6 及更高版本中不再受支持。

客户端应将 HTTP 状态码作为判断成功或失败的主要依据。若请求失败，客户端应以 message 字段作为错误信息的主要来源，并可使用其他附加信息获取进一步上下文。

Swagger 接口文档

生成的 Swagger API 定义可在 rpc.swagger.json 中找到。

5 - gRPC 命名与发现

etcd 提供了一个 gRPC 解析器，用于支持一种替代名称系统，该系统从 etcd 获取端点以发现 gRPC 服务。其底层机制基于监听以服务名称为前缀的键的更新。

请注意，此功能为实验性功能，因为它依赖于 google.golang.org/grpc/resolver 包，而该包在 grpc-go 中仍处于实验阶段。

使用 go-grpc 实现 etcd 发现

etcd 客户端为使用 etcd 后端解析 gRPC 端点提供了 gRPC 解析器。该解析器通过一个 etcd 客户端进行初始化：

import (
	clientv3 "go.etcd.io/etcd/client/v3"
	etcdnaming "go.etcd.io/etcd/client/v3/naming/resolver"

	"google.golang.org/grpc"
)

...

cli, err := clientv3.NewFromURL("http://localhost:2379")
if err != nil {
    // ...
}
r, err := etcdnaming.NewBuilder(cli)
if err != nil {
    // ...
}
conn, gerr := grpc.NewClient("my-service", grpc.WithResolvers(r), ...)

管理服务端点

etcd 解析器将解析目标前缀下所有以 “/” 分隔的键（例如 “foo/bar/my-service/"）视为潜在服务端点，这些键对应的值需为 JSON 编码格式（历史版本为 go-grpc naming.Update）。通过创建新键将端点添加至服务，通过删除键将端点从服务中移除。

添加端点

可通过 etcdctl 向服务添加新的端点：

ETCDCTL_API=3 etcdctl put foo/bar/my-service/1.2.3.4 '{"Addr":"1.2.3.4"}'

etcd 客户端的 endpoints.Manager 方法还可注册新的端点，其键与 Addr 匹配：

em := endpoints.NewManager(client, "foo/bar/my-service")
err := em.AddEndpoint(context.TODO(),"foo/bar/my-service/e1", endpoints.Endpoint{Addr:"1.2.3.4"})

当通过多个端点连接服务时，若要启用轮询负载均衡，可使用 gRPC 内置的轮询负载均衡器配置连接：

conn, gerr := grpc.NewClient("etcd:///foo", grpc.WithResolvers(etcdResolver),
grpc.WithDefaultServiceConfig(`{"loadBalancingPolicy":"round_robin"}`))

删除端点

可通过 etcdctl 从服务中删除主机：

ETCDCTL_API=3 etcdctl del foo/bar/my-service/1.2.3.4

etcd 客户端的 endpoints.Manager 方法还支持删除端点：

em := endpoints.NewManager(client, "foo/bar/my-service")
err := em.DeleteEndpoint(context.TODO(), "foo/bar/my-service/e1")

使用租约注册端点

使用租约注册端点可确保，若主机无法维持保活心跳（例如其所在机器发生故障），该端点将从服务中移除：

lease=`ETCDCTL_API=3 etcdctl lease grant 5 | cut -f2 -d' '`
ETCDCTL_API=3 etcdctl put --lease=$lease my-service/1.2.3.4 '{"Addr":"1.2.3.4"}'
ETCDCTL_API=3 etcdctl lease keep-alive $lease

在 Go 语言中：

em := endpoints.NewManager(client, "foo/bar/my-service")
err := em.AddEndpoint(context.TODO(), "foo/bar/my-service/e1", endpoints.Endpoint{Addr:"1.2.3.4"})

原子性更新端点

若需在单个事务中修改多个端点，可直接使用 endpoints.Manager：

em := endpoints.NewManager(c, "foo")

err := em.Update(context.TODO(), []*endpoints.UpdateWithOpts{
    endpoints.NewDeleteUpdateOpts("foo/bar/my-service/e1", endpoints.Endpoint{Addr: "1.2.3.4"}),
	endpoints.NewAddUpdateOpts("foo/bar/my-service/e1", endpoints.Endpoint{Addr: "1.2.3.14"})})

6 - 将 etcd 集成到 Go 应用中

etcd embed go 包提供了一种简便方式，可将 etcd 服务器直接嵌入应用程序。

有关详细信息，请参见 embed 包文档 。

7 - 系统限制

请求大小限制

etcd 专为处理典型的元数据类小规模键值对而设计。虽然较大请求也能正常工作，但可能增加其他请求的延迟。默认情况下，任何请求的最大大小为 1.5 MiB。此限制可通过 etcd 服务器的 --max-request-bytes 标志进行配置。

存储容量限制

默认存储大小限制为 2 GiB，可通过 --quota-backend-bytes 标志进行配置。在常规环境中，建议最大大小为 8 GiB，若配置值超过此限制，etcd 在启动时会发出警告。

8 - etcd 功能

本文概述了 etcd 的各项功能，旨在帮助用户更好地理解这些功能及其相关弃用流程。若想了解 etcd 功能的开发方式，请参阅 开发指南 。

etcd 功能分为三个阶段：实验性、稳定和不安全。可通过运行 etcd --help 获取功能列表。

实验性

为获取早期反馈，任何新功能通常以实验性功能的形式添加。可通过标志名称识别实验性功能，其名称应以 --experimental 为前缀。使用实验性功能时，请注意以下事项：

• 由于缺乏用户测试，该功能可能存在缺陷。启用该功能可能无法按预期工作。
• 默认情况下处于禁用状态。
• 项目团队可能随时停止支持该功能，恕不另行通知。
  • 若该功能未晋升为稳定功能，则可在下一个次要版本或主要版本中直接移除，无需遵循功能弃用 政策。
  • 项目团队欢迎用户报告与实验性功能相关的问题。但此类问题的优先级可能低于与稳定功能相关的问题。
• 实验性功能晋升为稳定功能 时，其实验性功能标志将被弃用。应尽快改用稳定功能标志。

稳定

这是 etcd 中功能最常见的阶段。稳定功能具有以下特征：

• 作为 etcd 支持版本的一部分提供支持。
• 可以默认启用。
• 停止支持必须遵循功能弃用 政策。

不安全

不安全功能较为罕见，列于 etcd 使用文档的 Unsafe feature: 章节中。默认情况下，这些功能处于禁用状态。使用时应谨慎，并遵循文档说明。不安全功能可能在下一个次要版本或主要版本中被移除，且无需遵循功能弃用策略。

功能弃用

实验性

当实验性功能进入稳定阶段时，即被弃用。

• 实验性功能的文档将显示弃用提示，并建议使用相关的稳定功能标志。例如 DEPRECATED. Use <feature-name> instead.
• 已弃用的功能将在后续版本中移除。

稳定

随着项目演进，某些稳定功能有时可能需要被弃用并移除。当发生这种情况时：

• 功能文档将在计划发布前显示警告消息。例如 To be deprecated in <release>.。若已有新功能计划替代 To be deprecated 功能，则文档还将提供相应说明。例如 Use <feature-name> instead.。
• 该功能将在计划发布中被弃用。此时，功能文档将显示弃用消息，并建议使用相关稳定功能。例如 DEPRECATED. Use <feature-name> instead.。
• 已弃用的功能将在后续发布中移除。

9 - API 参考

本文 API 参考由命名的 .proto 文件自动生成。

服务 Auth (api/etcdserverpb/rpc.proto)

服务 Cluster (api/etcdserverpb/rpc.proto)

服务 KV (api/etcdserverpb/rpc.proto)

服务 Lease (api/etcdserverpb/rpc.proto)

服务 Maintenance (api/etcdserverpb/rpc.proto)

服务 Watch (api/etcdserverpb/rpc.proto)

消息 AlarmMember (api/etcdserverpb/rpc.proto)

消息 AlarmRequest (api/etcdserverpb/rpc.proto)

消息 AlarmResponse (api/etcdserverpb/rpc.proto)

消息 AuthDisableRequest (api/etcdserverpb/rpc.proto)

消息 AuthDisableResponse (api/etcdserverpb/rpc.proto)

消息 AuthEnableRequest (api/etcdserverpb/rpc.proto)

消息 AuthEnableResponse (api/etcdserverpb/rpc.proto)

消息 AuthRoleAddRequest (api/etcdserverpb/rpc.proto)

消息 AuthRoleAddResponse (api/etcdserverpb/rpc.proto)

消息 AuthRoleDeleteRequest (api/etcdserverpb/rpc.proto)

消息 AuthRoleDeleteResponse (api/etcdserverpb/rpc.proto)

消息 AuthRoleGetRequest (api/etcdserverpb/rpc.proto)

消息 AuthRoleGetResponse (api/etcdserverpb/rpc.proto)

消息 AuthRoleGrantPermissionRequest (api/etcdserverpb/rpc.proto)

消息 AuthRoleGrantPermissionResponse (api/etcdserverpb/rpc.proto)

消息 AuthRoleListRequest (api/etcdserverpb/rpc.proto)

消息 AuthRoleListResponse (api/etcdserverpb/rpc.proto)

消息 AuthRoleRevokePermissionRequest (api/etcdserverpb/rpc.proto)

消息 AuthRoleRevokePermissionResponse (api/etcdserverpb/rpc.proto)

消息 AuthStatusRequest (api/etcdserverpb/rpc.proto)

消息 AuthStatusResponse (api/etcdserverpb/rpc.proto)

消息 AuthUserAddRequest (api/etcdserverpb/rpc.proto)

消息 AuthUserAddResponse (api/etcdserverpb/rpc.proto)

消息 AuthUserChangePasswordRequest (api/etcdserverpb/rpc.proto)

消息 AuthUserChangePasswordResponse (api/etcdserverpb/rpc.proto)

消息 AuthUserDeleteRequest (api/etcdserverpb/rpc.proto)

消息 AuthUserDeleteResponse (api/etcdserverpb/rpc.proto)

消息 AuthUserGetRequest (api/etcdserverpb/rpc.proto)

消息 AuthUserGetResponse (api/etcdserverpb/rpc.proto)

消息 AuthUserGrantRoleRequest (api/etcdserverpb/rpc.proto)

消息 AuthUserGrantRoleResponse (api/etcdserverpb/rpc.proto)

消息 AuthUserListRequest (api/etcdserverpb/rpc.proto)

消息 AuthUserListResponse (api/etcdserverpb/rpc.proto)

消息 AuthUserRevokeRoleRequest (api/etcdserverpb/rpc.proto)

消息 AuthUserRevokeRoleResponse (api/etcdserverpb/rpc.proto)

消息 AuthenticateRequest (api/etcdserverpb/rpc.proto)

消息 AuthenticateResponse (api/etcdserverpb/rpc.proto)

消息 CompactionRequest (api/etcdserverpb/rpc.proto)

CompactionRequest 对键值存储执行压缩，直至指定的修订版本。所有修订版本小于压缩修订版本的已覆盖键将被移除。

消息 CompactionResponse (api/etcdserverpb/rpc.proto)

消息 Compare (api/etcdserverpb/rpc.proto)

消息 DefragmentRequest (api/etcdserverpb/rpc.proto)

消息 DefragmentResponse (api/etcdserverpb/rpc.proto)

消息 DeleteRangeRequest (api/etcdserverpb/rpc.proto)

消息 DeleteRangeResponse (api/etcdserverpb/rpc.proto)

消息 DowngradeInfo (api/etcdserverpb/rpc.proto)

消息 DowngradeRequest (api/etcdserverpb/rpc.proto)

消息 DowngradeResponse (api/etcdserverpb/rpc.proto)

消息 DowngradeVersionTestRequest (api/etcdserverpb/rpc.proto)

DowngradeVersionTestRequest 仅用于测试。请求中的版本将被读取为 WAL 记录版本。如果降级目标版本小于该版本，则降级（在线）或迁移（离线）不安全，因此不应允许。

消息 HashKVRequest (api/etcdserverpb/rpc.proto)

消息 HashKVResponse (api/etcdserverpb/rpc.proto)

消息 HashRequest (api/etcdserverpb/rpc.proto)

消息 HashResponse (api/etcdserverpb/rpc.proto)

消息 LeaseCheckpoint (api/etcdserverpb/rpc.proto)

消息 LeaseCheckpointRequest (api/etcdserverpb/rpc.proto)

消息 LeaseCheckpointResponse (api/etcdserverpb/rpc.proto)

消息 LeaseGrantRequest (api/etcdserverpb/rpc.proto)

消息 LeaseGrantResponse (api/etcdserverpb/rpc.proto)

消息 LeaseKeepAliveRequest (api/etcdserverpb/rpc.proto)

消息 LeaseKeepAliveResponse (api/etcdserverpb/rpc.proto)

消息 LeaseLeasesRequest (api/etcdserverpb/rpc.proto)

消息 LeaseLeasesResponse (api/etcdserverpb/rpc.proto)

消息 LeaseRevokeRequest (api/etcdserverpb/rpc.proto)

消息 LeaseRevokeResponse (api/etcdserverpb/rpc.proto)

消息 LeaseStatus (api/etcdserverpb/rpc.proto)

消息 LeaseTimeToLiveRequest (api/etcdserverpb/rpc.proto)

消息 LeaseTimeToLiveResponse (api/etcdserverpb/rpc.proto)

消息 Member (api/etcdserverpb/rpc.proto)

消息 MemberAddRequest (api/etcdserverpb/rpc.proto)

消息 MemberAddResponse (api/etcdserverpb/rpc.proto)

消息 MemberListRequest (api/etcdserverpb/rpc.proto)

消息 MemberListResponse (api/etcdserverpb/rpc.proto)

消息 MemberPromoteRequest (api/etcdserverpb/rpc.proto)

消息 MemberPromoteResponse (api/etcdserverpb/rpc.proto)

消息 MemberRemoveRequest (api/etcdserverpb/rpc.proto)

消息 MemberRemoveResponse (api/etcdserverpb/rpc.proto)

消息 MemberUpdateRequest (api/etcdserverpb/rpc.proto)

消息 MemberUpdateResponse (api/etcdserverpb/rpc.proto)

消息 MoveLeaderRequest (api/etcdserverpb/rpc.proto)

消息 MoveLeaderResponse (api/etcdserverpb/rpc.proto)

消息 PutRequest (api/etcdserverpb/rpc.proto)

消息 PutResponse (api/etcdserverpb/rpc.proto)

消息 RangeRequest (api/etcdserverpb/rpc.proto)

消息 RangeResponse (api/etcdserverpb/rpc.proto)

消息 RequestOp (api/etcdserverpb/rpc.proto)

消息 ResponseHeader (api/etcdserverpb/rpc.proto)

消息 ResponseOp (api/etcdserverpb/rpc.proto)

消息 SnapshotRequest (api/etcdserverpb/rpc.proto)

消息 SnapshotResponse (api/etcdserverpb/rpc.proto)

消息 StatusRequest (api/etcdserverpb/rpc.proto)

消息 StatusResponse (api/etcdserverpb/rpc.proto)

消息 TxnRequest (api/etcdserverpb/rpc.proto)

MultiOp 原语

源自 Google PaxosDB 论文：我们的实现基于一种强大的原语，称为 MultiOp。除迭代外，所有数据库操作均通过一次 MultiOp 调用实现。MultiOp 以原子方式应用，包含三个组成部分：1. 一组称为 guard 的测试。guard 中的每个测试检查数据库中的单个条目。测试可检查值是否存在或不存在，或与给定值进行比较。guard 中的两个不同测试可作用于数据库中的同一或不同条目。所有测试均被应用，MultiOp 返回测试结果。若所有测试均为真，则执行 t op（参见下文第 2 项），否则执行 f op（参见下文第 3 项）。2. 一组称为 t op 的数据库操作。列表中的每个操作为插入、删除或查找操作，且作用于单个数据库条目。列表中的两个不同操作可作用于数据库中的同一或不同条目。当 guard 求值为真时执行这些操作。3. 一组称为 f op 的数据库操作。与 t op 类似，但在 guard 求值为假时执行。

消息 TxnResponse (api/etcdserverpb/rpc.proto)

消息 WatchCancelRequest (api/etcdserverpb/rpc.proto)

消息 WatchCreateRequest (api/etcdserverpb/rpc.proto)

消息 WatchProgressRequest (api/etcdserverpb/rpc.proto)

请求在监听响应流中尽快发送监听流进度状态。

消息 WatchRequest (api/etcdserverpb/rpc.proto)

消息 WatchResponse (api/etcdserverpb/rpc.proto)

消息 Event (api/mvccpb/kv.proto)

消息 KeyValue (api/mvccpb/kv.proto)

消息 Lease (server/lease/leasepb/lease.proto)

消息 LeaseInternalRequest (server/lease/leasepb/lease.proto)

消息 LeaseInternalResponse (server/lease/leasepb/lease.proto)

消息 Permission (api/authpb/auth.proto)

权限是一个单一实体

message Role (api/authpb/auth.proto)

角色是 authRoles 存储桶中的单个条目。

message User (api/authpb/auth.proto)

用户是存储桶 authUsers 中的单个条目

message UserAddOptions (api/authpb/auth.proto)

10 - API 参考：并发

本文 API 参考由命名的 .proto 文件自动生成。

服务 Lock (server/etcdserver/api/v3lock/v3lockpb/v3lock.proto)

锁服务将客户端锁功能以 gRPC 接口的形式暴露。

消息 LockRequest (server/etcdserver/api/v3lock/v3lockpb/v3lock.proto)

消息 LockResponse (server/etcdserver/api/v3lock/v3lockpb/v3lock.proto)

消息 UnlockRequest (server/etcdserver/api/v3lock/v3lockpb/v3lock.proto)

消息 UnlockResponse (server/etcdserver/api/v3lock/v3lockpb/v3lock.proto)

服务 Election (server/etcdserver/api/v3election/v3electionpb/v3election.proto)

选举服务通过 gRPC 接口向客户端暴露选举功能。

消息 CampaignRequest (server/etcdserver/api/v3election/v3electionpb/v3election.proto)

消息 CampaignResponse (server/etcdserver/api/v3election/v3electionpb/v3election.proto)

消息 LeaderKey (server/etcdserver/api/v3election/v3electionpb/v3election.proto)

消息 LeaderRequest (server/etcdserver/api/v3election/v3electionpb/v3election.proto)

消息 LeaderResponse (server/etcdserver/api/v3election/v3electionpb/v3election.proto)

消息 ProclaimRequest (server/etcdserver/api/v3election/v3electionpb/v3election.proto)

消息 ProclaimResponse (server/etcdserver/api/v3election/v3electionpb/v3election.proto)

消息 ResignRequest (server/etcdserver/api/v3election/v3electionpb/v3election.proto)

消息 ResignResponse (server/etcdserver/api/v3election/v3electionpb/v3election.proto)

消息 Event (api/mvccpb/kv.proto)

消息 KeyValue (api/mvccpb/kv.proto)