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
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
扩展
go lib 库