Etcd 命令行工具

etcdctl 命令行工具

etcdctl 使用

etcdctl 是一个命令行客户端，它能提供一些简洁的命令，供用户直接跟 etcd 服务打交道，而无需基于 HTTP API 方式。这在某些情况下将很方便，例如用户对服务进行测试或者手动修改数据库内容。我们也推荐在刚接触 etcd 时通过 etcdctl 命令来熟悉相关的操作，这些操作跟 HTTP API 实际上是对应的。

etcd 项目二进制发行包中已经包含了 etcdctl 工具，没有的话，可以从 github.com/coreos/etcd/releases 下载。

etcdctl 支持如下的命令，大体上分为数据库操作和非数据库操作两类，后面将分别进行解释。

etcd 有两个版本，使用时，需要通过环境变量区分：

export ETCDCTL_API=2
export ETCDCTL_API=3

help

etcdctl --help ...

$ etcdctl --help
NAME:
	etcdctl - A simple command line client for etcd3.

USAGE:
	etcdctl [flags]

VERSION:
	3.5.14

API VERSION:
	3.5


COMMANDS:
	alarm disarm		Disarms all alarms
	alarm list		Lists all alarms
	auth disable		Disables authentication
	auth enable		Enables authentication
	auth status		Returns authentication status
	check datascale		Check the memory usage of holding data for different workloads on a given server endpoint.
	check perf		Check the performance of the etcd cluster
	compaction		Compacts the event history in etcd
	defrag			Defragments the storage of the etcd members with given endpoints
	del			Removes the specified key or range of keys [key, range_end)
	elect			Observes and participates in leader election
	endpoint hashkv		Prints the KV history hash for each endpoint in --endpoints
	endpoint health		Checks the healthiness of endpoints specified in `--endpoints` flag
	endpoint status		Prints out the status of endpoints specified in `--endpoints` flag
	get			Gets the key or a range of keys
	help			Help about any command
	lease grant		Creates leases
	lease keep-alive	Keeps leases alive (renew)
	lease list		List all active leases
	lease revoke		Revokes leases
	lease timetolive	Get lease information
	lock			Acquires a named lock
	make-mirror		Makes a mirror at the destination etcd cluster
	member add		Adds a member into the cluster
	member list		Lists all members in the cluster
	member promote		Promotes a non-voting member in the cluster
	member remove		Removes a member from the cluster
	member update		Updates a member in the cluster
	move-leader		Transfers leadership to another etcd cluster member.
	put			Puts the given key into the store
	role add		Adds a new role
	role delete		Deletes a role
	role get		Gets detailed information of a role
	role grant-permission	Grants a key to a role
	role list		Lists all roles
	role revoke-permission	Revokes a key from a role
	snapshot restore	Restores an etcd member snapshot to an etcd directory
	snapshot save		Stores an etcd node backend snapshot to a given file
	snapshot status		[deprecated] Gets backend snapshot status of a given file
	txn			Txn processes all the requests in one transaction
	user add		Adds a new user
	user delete		Deletes a user
	user get		Gets detailed information of a user
	user grant-role		Grants a role to a user
	user list		Lists all users
	user passwd		Changes password of user
	user revoke-role	Revokes a role from a user
	version			Prints the version of etcdctl
	watch			Watches events stream on keys or prefixes

OPTIONS:
      --cacert=""				verify certificates of TLS-enabled secure servers using this CA bundle
      --cert=""					identify secure client using this TLS certificate file
      --command-timeout=5s			timeout for short running command (excluding dial timeout)
      --debug[=false]				enable client-side debug logging
      --dial-timeout=2s				dial timeout for client connections
  -d, --discovery-srv=""			domain name to query for SRV records describing cluster endpoints
      --discovery-srv-name=""			service name to query when using DNS discovery
      --endpoints=[127.0.0.1:2379]		gRPC endpoints
  -h, --help[=false]				help for etcdctl
      --hex[=false]				print byte strings as hex encoded strings
      --insecure-discovery[=true]		accept insecure SRV records describing cluster endpoints
      --insecure-skip-tls-verify[=false]	skip server certificate verification (CAUTION: this option should be enabled only for testing purposes)
      --insecure-transport[=true]		disable transport security for client connections
      --keepalive-time=2s			keepalive time for client connections
      --keepalive-timeout=6s			keepalive timeout for client connections
      --key=""					identify secure client using this TLS key file
      --password=""				password for authentication (if this option is used, --user option shouldn't include password)
      --user=""					username[:password] for authentication (prompt if password is not supplied)
  -w, --write-out="simple"			set the output format (fields, json, protobuf, simple, table)

常用命令介绍

子命令	说明
alarm disarm	接触所有的报警
alarm list	列出所有的报警
auth disable	禁用 authentication
auth enable	启用 authentication
check datascale	对于给定服务实例，检查持有数据存储使用率
check perf	检查 etcd 集群的性能表现
compaction	压缩 etcd 中的事件历史
defrag	整理给定 etcd 实例的存储碎片
del	移除指定范围 `[key, range_end)` 的键值对
elect	加入 leader 选举
endpoint hashkv	打印指定 etcd 实例的历史键值对 hash 信息
endpoint health	打印指定 etcd 实例的健康信息
endpoint status	打印指定 etcd 实例的状态信息
get	获取键值对
help	帮助命令
lease grant	创建 leases
lease keep-alive	刷新 leases
lease list	列出所有有效的 leases
lease revoke	撤销 leases
lease timetolive	获取 lease 信息
lock	获取一个命名锁
make-mirror	指定一个 etcd 集群作为镜像集群
member add	增加一个成员到集群
member list	列出集群的所有成员
member promote	提升集群中的一个 non-voting 成员
member remove	移除集群中的成员
member update	更新集群中的成员信息
migrate	迁移 V2 存储中的键值对到 MVCC 存储
move-leader	转移 etcd 集群的 leader 给另一个 etcd 成员
put	写入键值对
role add	增加一个角色
role delete	删除一个角色
role get	获取某个角色的详细信息
role grant-permission	给某个角色授予 key
role list	列出所有的角色
role revoke-permission	撤销一个角色的 key
shapshot restore	恢复快照
shapshot save	存储某一个 etcd 节点的快照文件主指定位直
snapshot status	获取指定文件的后端快照文件状态
txn	Txn 在一个事务内处理所有的请求
user add	增加一个用户
user delete	删除某个用户
user get	获取某个用户的详细信息
user grant-role	将某个角色授予某个用户
user list	列出所有的用户
user passwd	更改某个用户的密码
user revoke-role	撤销某个用户的角色
version	输出 etcdctl 的版本
watch	检测指定键或前缀的事件流

etcdctl 命令

etcdctl 命令大体上分为数据库操作和非数据库操作

示例的 etcdctl 和 etcd API 版本如下：

$ etcdctl version
etcdctl version: 3.5.14
API version: 3.5

数据库操作

数据库操作围绕对键值和目录的 CRUD （符合 REST 风格的一套操作：Create）完整生命周期的管理
- CRUD 即 Create, Read, Update, Delete，是符合 REST 风格的一套 API 操作。
etcd 在键的组织上采用了层次化的空间结构（类似于文件系统中目录的概念），用户指定的键可以为单独的名字，如 testkey，此时实际上放在根目录 / 下面，也可以为指定目录结构，如 cluster1/node2/testkey，则将创建相应的目录结构

键操作

键操作包括常见的增(PUT)、删(DELETE)、改(PUT)、查(GET)

put

put 设置或者更新某个键的值

$ etcdctl put /test/key1 hello1
OK
$ etcdctl put /test/key2 hello2
OK
$ etcdctl put /test/key3 hello3
OK

支持 TTL 设置。

set

# 设置 key 的 ttl，过期后会被自动删除
$ etcdctl set tempkey "hello world" --ttl 5
hello world
$ etcdctl get tempkey
hello world
$ etcdctl get tempkey
Error:  100: Key not found (/tempkey) [1050]

get

get 获取指定键的值。例如

$ etcdctl get /test/key1
/test/key1
hello1

# 以十六进制格式返回
$ etcdctl get /test/key1 --hex
\x2f\x74\x65\x73\x74\x2f\x6b\x65\x79\x31
\x68\x65\x6c\x6c\x6f\x31

# 通过 --prefix 获取指定前缀的 keys
$ etcdctl get --prefix /test/key
/test/key1
hello1
/test/key2
hello2
/test/key3
hello3

# 通过 --limit=<n> 限制获取的数量
$ etcdctl get --prefix --limit=2 /test/key
/test/key1
hello1
/test/key2
hello2

# etcd 集群上键值存储的每个修改都会增加 etcd 集群的全局修订版本
# 通过 --rev=<n> 限定版本
$ etcdctl get --prefix --rev=3 /test/key
/test/key1
hello1
/test/key2
hello2
$ etcdctl get --prefix --rev=2 /test/key
/test/key1
hello1

# 根据 key 匹配获取
$ etcdctl get --from-key /test/k
/test/key1
hello1
/test/key2
hello2
/test/key3

其他支持的选项为：

--sort 对结果进行排序
--consistent 将请求发给主节点，保证获取内容的一致性

del

从 etcd 中删除一个或特定范围的键值。例如

# 1 表示删除了一个键
$ etcdctl del /test/key1
1

# 删除一个范围？已经不支持了
$ etcdctl del /test/key2 /test/key3
In etcd v3.6, the operation will be suspended for a few seconds to provide the user time to verify range.
1

# 删除并返回对应的键值
$ etcdctl del --prev-kv /test/key1
1  # 一个键被删除
/test/key1  # 被删除的键
hello1  # 被删除的值

# 删除指定前缀的键
$ etcdctl del --prefix /test/key
2

# 根据 key 匹配删除
$ etcdctl del --from-key /test/k
3  # 删除了 3 个键

watch

监测一个键值的变化，一旦键值发生更新，就会输出最新的值。例如，用户更新 /test/key1 键值为 hi1

# 先 watch，新控制台输入 etcdctl put /test/key1 hi1
$ etcdctl watch /test/key1
PUT
/test/key1
hi1

# 不支持监听多个键了
$ etcdctl watch /test/key1 /test/key2

$ 十六进制格式对 key 进行 watch，新控制台输入 etcdctl put /test/key1 hi1
$ etcdctl watch --hex /test/key1
PUT
\x2f\x74\x65\x73\x74\x2f\x6b\x65\x79\x31
\x68\x69\x31

$ 同时 watch 多个 key
$ etcdctl watch -i
watch /test/key1
watch /test/key2
# 新控制台输入 etcdctl put /test/key1 hi1 时的输出
PUT
/test/key1
hi1
PUT
# 新控制台输入 etcdctl put /test/key2 hi2 时的输出
/test/key2
hi2

# watch 历史改动
$ etcdctl watch --rev=15 /test/key1
DELETE
/test/key1

PUT
/test/key1
hi1
PUT
/test/key1

# watch 返回被修改的值和上一个修订版的值，新控制台输入 etcdctl put /test/key1 foo
$ etcdctl watch --prev-kv /test/key1
PUT
/test/key1
hi1  # 修改前的值
/test/key1
foo  # 修改后的值

经过压缩，etcd 会删除历史修订版本，并释放存储空间，且压缩后之前的历史数据不能再访问

compact

compact 命令用来压缩修订版本

$ etcdctl compact 10
compacted revision 10
$ etcdctl get --rev=8 /test/key1
{"level":"warn","ts":"2024-06-23T11:31:14.858324Z","logger":"etcd-client","caller":"v3@v3.5.14/retry_interceptor.go:63","msg":"retrying of unary invoker failed","target":"etcd-endpoints://0xc0004aa1e0/127.0.0.1:2379","attempt":0,"error":"rpc error: code = OutOfRange desc = etcdserver: mvcc: required revision has been compacted"}
Error: etcdserver: mvcc: required revision has been compacted

lease

ease 为租约的意思，类似与 Redis 中的 TTL(Time To Live)
etcd 中的键值对可以绑定到租约上，实现存活周期控制
授权租约
- 应用客户端可以为 etcd 集群里的键授权租约
- 当租约的 TTL 到期，租约就会过期，并且所有附带的键都将被删除

# 授权租约，TTL 为 60 秒
$ etcdctl lease grant 60
lease 12f790448cfde332 granted with TTL(60s)

# 附加键 foo 到租约 12f790448cfde332
$ etcdctl put --lease=12f790448cfde332 foo bar
OK

# watch 租约到期后，自动删除 foo 键
$ etcdctl watch foo
DELETE
foo

# 通过 ID 可以撤销租约，撤销租约将删除所附带的 key
$ etcdctl lease grant 600
lease 12f790448cfde336 granted with TTL(600s)
$ etcdctl lease list
found 1 leases
12f790448cfde336
$ etcdctl lease revoke 12f790448cfde336
lease 12f790448cfde336 revoked
$ etcdctl lease list
found 0 leases

# 租约刷新，应用客户端可以通过刷新其 TTL 保持租约存活
$ etcdctl lease grant 20
lease 12f790448cfde33b granted with TTL(20s)
$ etcdctl lease keep-alive 12f790448cfde33b
lease 12f790448cfde33b keepalived with TTL(20)
lease 12f790448cfde33b keepalived with TTL(20)
...

# 查询租期，应用客户端可以查询、续订租约，查看是否存在或是否已经过期
$ etcdctl lease grant 60
lease 12f790448cfde340 granted with TTL(60s)
$ etcdctl put --lease=12f790448cfde340 foo bar
OK
$ etcdctl lease timetolive 12f790448cfde340
lease 12f790448cfde340 granted with TTL(60s), remaining(40s)
$ etcdctl lease timetolive --keys 12f790448cfde340
lease 12f790448cfde340 granted with TTL(60s), remaining(29s), attached keys([foo])
$ $ etcdctl lease timetolive --keys 12f790448cfde340
lease 12f790448cfde340 already expired

非数据库操作

member 列表

通过 list、add、update、remove 命令列出、添加、更新、删除 etcd 实例到 etcd 集群中。

例如本地启动一个 etcd 服务实例后，可以用如下命令进行查看。

$ etcdctl member list
422a74f03b622fef, started, node1, http://10.10.10.10:2380, http://10.10.10.10:2379

endpoint 状态

$ alias etcdctl='etcdctl --endpoints=https://10.10.3.11:2379,https://10.10.3.12:2379,https://10.10.3.13:2379 --cacert=/etc/kubernetes/pki/etcd/ca.crt --cert=/etc/kubernetes/pki/etcd/server.crt --key=/etc/kubernetes/pki/etcd/server.key'
$ etcdctl endpoint status --write-out=table
$ etcdctl endpoint health

扩展

UI

go lib 库

go libs
etcd v3 的通信基于 gRPC，proto 文件是定义服务端和客户端通信接口的标准，基于 proto3 消息格式
- 发送到 etcd 服务器的每个 API 请求都是一个 gRPC 远程过程调用
Client struct 实现：
- Cluster etcd 集群节点信息
- KV 操作 key-value
- Lease 租约相关
- Watcher 观察订阅
- Auth 用户和权限
- Maintenance 处理如 tcd leader 迁移等
- 认证：Username 和 Password
- Lock Service 分布式共享锁支持
ResponseHeader 响应
- Revision 产生相应时键值存储的修订版本号
  - 应用服务可以使用修改号字段获取当前键值存储库最新的修订号
  - 应用程序指定历史修订已进行查询
- Raft_Term 产生响应时，成员的 Raft 称谓，使用此来检测集群何时完成一个新的 leader 选举
Txn 方式在单个事务中处理多个请求
- Txn 请求增加键值存储的修订版本，为每个完成的请求生成带有相同修订版本的事件，etcd 不容许在一个 Txn 中多次修改同一个 key
Compact 方法压缩 etcd 键值对存储中的事件历史，键值对存储应该定期压缩，否则事件历史会无限制的持续增长

F&Q

first path segment in URL cannot contain colon

$ etcdctl --endpoints=127.0.0.1:2371,127.0.0.1:2372,127.0.0.1:2373 member list
parse 127.0.0.1:2371: first path segment in URL cannot contain colon

# 正确命令
$ etcdctl --endpoints=//127.0.0.1:2371,//127.0.0.1:2372,//127.0.0.1:2373 member list