首页 etcdctl 使用小结
文章
取消

etcdctl 使用小结

发表于 2022/11/02
作者
10 分钟阅读

etcdctl 是 etcd 的命令行客户端，用于读写数据、集群管理、用户管理、角色管理等功能。

先看下官方使用说明：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85

I have no name!@057a56f3f1bc:/opt/bitnami/etcd$ etcdctl --help
NAME:
	etcdctl - A simple command line client for etcd3.

USAGE:
	etcdctl [flags]

VERSION:
	3.5.6

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)

数据库操作相关

put

顾名思义对键值添加或更新操作：

1
2
3
4

I have no name!@057a56f3f1bc:/opt/bitnami/etcd$ etcdctl put test/b "val1"
OK
I have no name!@057a56f3f1bc:/opt/bitnami/etcd$ etcdctl put test/bob "val2"
OK

get

顾名思义就是对键值查找操作：

查找指定 key：

1
2
3

I have no name!@057a56f3f1bc:/opt/bitnami/etcd$ etcdctl get test/b
test/b
val1

范围取值，左闭右开

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

I have no name!@057a56f3f1bc:/opt/bitnami/etcd$ etcdctl put test/k1 "v1"
OK
I have no name!@057a56f3f1bc:/opt/bitnami/etcd$ etcdctl put test/k2 "v2"
OK
I have no name!@057a56f3f1bc:/opt/bitnami/etcd$ etcdctl put test/k3 "v3"
OK
I have no name!@057a56f3f1bc:/opt/bitnami/etcd$ etcdctl put test/k4 "v4"
OK
I have no name!@057a56f3f1bc:/opt/bitnami/etcd$ etcdctl put test/k5 "v5"
OK
I have no name!@057a56f3f1bc:/opt/bitnami/etcd$ etcdctl get test/k3 test/k5
test/k3
v3
test/k4
v4

指定大于等于指定 key 的键值，

1
2
3
4
5
6
7
8
9

I have no name!@057a56f3f1bc:/opt/bitnami/etcd$ etcdctl get --from-key  test/k2
test/k2
v2
test/k3
v3
test/k4
v4
test/k5
v5

按前缀查找，

1
2
3
4
5
6
7
8
9
10
11

I have no name!@057a56f3f1bc:/opt/bitnami/etcd$ etcdctl get --prefix test/k
test/k1
v1
test/k2
v2
test/k3
v3
test/k4
v4
test/k5
v5

限制查找数量，等同于关系型数据库 sql 语句中的 limit，

1
2
3
4
5
6
7

I have no name!@057a56f3f1bc:/opt/bitnami/etcd$ etcdctl get --prefix --limit=3 test/k
test/k1
v1
test/k2
v2
test/k3
v3

以十六进制返回键和值，

1
2
3

I have no name!@057a56f3f1bc:/opt/bitnami/etcd$ etcdctl get --hex test/b
\x74\x65\x73\x74\x2f\x62
\x76\x61\x6c\x31

以 json 格式获取键值对的详细信息，此时 key 和 value 都是 base64编码后的数据，需要解码获取原始数据，

1
2

I have no name!@057a56f3f1bc:/opt/bitnami/etcd$ etcdctl get --write-out json test/b
{"header":{"cluster_id":14841639068965178418,"member_id":10276657743932975437,"revision":18,"raft_term":3},"kvs":[{"key":"dGVzdC9i","create_revision":12,"mod_revision":12,"version":1,"value":"dmFsMQ=="}],"count":1}

对于上面的数据，

  • cluster_id，集群 ID
  • member_id，节点成员 ID
  • revision，全局版本号，自动递增，每次数据更新操作都会使版本号自动递增
  • create_revision，创建时的全局版本号
  • mod_revision，最近修改后的全局版本号
  • version，该键自己的版本号，每次更新操作都会自动递增，如果该键删除并重建，会重新从1开始
  • key，base64编码后的 key
  • value，base64编码后的 value

del

删除键，返回1表示删除成功，返回0表示不存在

1
2

I have no name!@057a56f3f1bc:/opt/bitnami/etcd$ etcdctl del test/b
1

watch

用于监听指定key，阻塞等待，一旦 key 的 value 发生更新会输出返回值。类似于 redis 中的 watch 命令。

1
2
3
4

I have no name!@057a56f3f1bc:/opt/bitnami/etcd$ etcdctl watch test/bob
PUT   # 在其他终端，执行 etcdctl put test/bob bob 命令
test/bob
bob

lease

租约，类似于 redis 中的过期时间，但是将键值对绑定到租约上，当租约到期，绑定了该租约的键都会被删除。

创建租约，注意：在租约被创建后就开始计时了

1
2

I have no name!@057a56f3f1bc:/opt/bitnami/etcd$ etcdctl lease grant 10
lease 694d8548043b1c29 granted with TTL(10s)

如果租约不存在，或已过期，将键值绑定到租约上会失败：

1
2
3

I have no name!@057a56f3f1bc:/opt/bitnami/etcd$ etcdctl put --lease=694d8548043b1c29 testlease val
{"level":"warn","ts":"2022-11-02T06:49:43.912Z","logger":"etcd-client","caller":"v3@v3.5.6/retry_interceptor.go:62","msg":"retrying of unary invoker failed","target":"etcd-endpoints://0xc0000ea380/127.0.0.1:2379","attempt":0,"error":"rpc error: code = NotFound desc = etcdserver: requested lease not found"}
Error: etcdserver: requested lease not found

成功的话会是：

1
2
3
4
5
6
7

I have no name!@057a56f3f1bc:/opt/bitnami/etcd$ etcdctl lease grant 100
lease 694d8548043b1c2d granted with TTL(100s)
I have no name!@057a56f3f1bc:/opt/bitnami/etcd$ etcdctl put --lease=694d8548043b1c2d testlease val
OK
I have no name!@057a56f3f1bc:/opt/bitnami/etcd$ etcdctl get testlease
testlease
val

查看租约到期情况：

1
2
3
4

I have no name!@057a56f3f1bc:/opt/bitnami/etcd$ etcdctl lease timetolive 694d8548043b1c2d
lease 694d8548043b1c2d granted with TTL(100s), remaining(3s)
I have no name!@057a56f3f1bc:/opt/bitnami/etcd$ etcdctl lease timetolive 694d8548043b1c2d
lease 694d8548043b1c2d already expired

撤销租约：

1
2
3
4

I have no name!@057a56f3f1bc:/opt/bitnami/etcd$ etcdctl lease grant 200
lease 694d8548043b1c33 granted with TTL(200s)
I have no name!@057a56f3f1bc:/opt/bitnami/etcd$ etcdctl lease revoke 694d8548043b1c33
lease 694d8548043b1c33 revoked

刷新租约：

1
2
3
4

I have no name!@057a56f3f1bc:/opt/bitnami/etcd$ etcdctl lease grant 200
lease 694d8548043b1c36 granted with TTL(200s)
I have no name!@057a56f3f1bc:/opt/bitnami/etcd$ etcdctl lease keep-alive 694d8548043b1c36
lease 694d8548043b1c36 keepalived with TTL(200)

lock

对指定key 加锁，只有当正常退出且释放锁后，lock 命令的退出码是0，否则这个锁会一直被占用。

1
2

I have no name!@057a56f3f1bc:/opt/bitnami/etcd$ etcdctl lock lock1
lock1/694d8548043b1c6a

权限控制

role

创建角色

1
2

I have no name!@057a56f3f1bc:/opt/bitnami/etcd$ etcdctl role add testrole
Role testrole created

查看角色

1
2
3
4
5
6

I have no name!@057a56f3f1bc:/opt/bitnami/etcd$ etcdctl role list
testrole
I have no name!@057a56f3f1bc:/opt/bitnami/etcd$ etcdctl role get testrole
Role testrole
KV Read:
KV Write:

绑定权限，可选权限有 read、write、readwrite，

1
2
3
4
5
6
7
8

I have no name!@057a56f3f1bc:/opt/bitnami/etcd$ etcdctl role grant-permission testrole readwrite testkey
Role testrole updated
I have no name!@057a56f3f1bc:/opt/bitnami/etcd$ etcdctl role get testrole
Role testrole
KV Read:
	testkey
KV Write:
	testkey

撤销权限，

1
2
3
4
5
6

I have no name!@057a56f3f1bc:/opt/bitnami/etcd$ etcdctl role revoke-permission testrole testkey
Permission of key testkey is revoked from role testrole
I have no name!@057a56f3f1bc:/opt/bitnami/etcd$ etcdctl role get testrole
Role testrole
KV Read:
KV Write:

删除角色，

1
2

I have no name!@057a56f3f1bc:/opt/bitnami/etcd$ etcdctl role del testrole
Role testrole deleted

user

添加用户，

1
2
3
4

I have no name!@057a56f3f1bc:/opt/bitnami/etcd$ etcdctl user add user1
Password of user1:
Type password of user1 again for confirmation:
User user1 created

给用户绑定 role，

1
2
3
4

I have no name!@057a56f3f1bc:/opt/bitnami/etcd$ etcdctl role add role1
Role role1 created
I have no name!@057a56f3f1bc:/opt/bitnami/etcd$ etcdctl user grant-role user1 role1
Role role1 is granted to user user1

给用户移除 role，

1
2

I have no name!@057a56f3f1bc:/opt/bitnami/etcd$ etcdctl user revoke-role user1 role1
Role role1 is revoked from user user1

查看用户，

1
2
3

I have no name!@057a56f3f1bc:/opt/bitnami/etcd$ etcdctl user get user1
User: user1
Roles: role1

删除用户，

1
2

I have no name!@057a56f3f1bc:/opt/bitnami/etcd$ etcdctl user del user1
User user1 deleted
技术
etcd
本文由作者按照 CC BY 4.0 进行授权
文章内容