etcdctl 操作指令
etcdctl是etcd 项目二机制包下的一个命令行客户端，它能提供一些简洁的命令，便于进行服务测试和修改数据库内容，而无需基于 HTTP API方式。etcdctl支持的命令大体上分为数据库操作和非数据库操作两类。这些操作跟 HTTP API 基本上是对应的。etcdctl 在两个不同的 etcd 版本下的行为方式也完全不同， 可通过环境变量设置所需要的版本
# v2 版本
export ETCDCTL_API=2
# v3 版本， 推荐使用v3版本，后面的操作都是基于v3版本
export ETCDCTL_API=3
如下是详细的etcdctl 操作指令
[root@iZuf6g3hri8hvnuqng6id7Z ~] etcdctl --help
NAME:
etcdctl - A simple command line client for etcd3.
USAGE:
etcdctl [flags]
VERSION:
3.5.2
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)
数据库操作相关
数据库操作围绕对键值和目录的CRUD(增删改查)完整生命周期的管理。
etcd在键的组织上采用了层次化的空间结构(类似于文件系统中目录的概念)，用户指定的键可以为单独的名字，如:testkey，此时实际上放在根目录/下面，也可以为指定目录结构，如/cluster1/node2/testkey，则将创建相应的目录结构。
-
put
设置或者更新某个键值# 写入三对键值，/test/key、/test/key2 和 /test/key3 # etcdctl 在不指定`endpoints`时，默认链接127.0.0.1:2379 etcdctl put /test/key "Hello world" etcdctl put /test/key2 "Hello world2" etcdctl put /test/key3 "Hello world3"通过如下操作指令获取put操作的详细指令介绍:
etcdctl put -h -
get
- 获取对应键的值
etcdctl get /test/key /test/key Hello world以json 格式获取键值对的详细信息，此时json 返回的key和value都是base64 编码后的数据，需要解码获取原始数据
etcdctl get /test/key --write-out json {"header": {"cluster_id":14841639068965178418,"member_id":1027665774 3932975437,"revision":51,"raft_term":8},"kvs": [{"key":"L3Rlc3Qva2V5","create_revision":9,"mod_revision":51,"v ersion":9,"value":"SGVsbG8="}],"count":1}- revision: 全局的版本好，自动递增，没次数据更新操作都会使版本好自动递增
- raft_term： 集群中leader 任期号，每一次的leader 节点选举，都会导致term 递增
- create_revision"： 该键被创建时对应的全局版本号
- mod_revision： 最新修改后对应的全局版本号
- version： 该键自己的版本号，每次更新操作都会自动递增，也可以理解为修改次数，如果该键被删除后再创建，version 又从1开始
- key： 对应的键经过base64 编码之后的值
- value： key对应value 经过base64编码后的值
- 只读取对应的value
etcdctl get /test/key --print-value-only Hello world- 以十六进制格式返回 --hex
etcdctl get test --hex \x74\x65\x73\x74 \x61\x62\x63\x64- 范围取值
etcdctl get /test/key /test/testkey3 /test/key Hello world /test/key2 Hello world2 /test/key3 Hello world3获取了区间 [testkey, testkey3] 的键值对
- 指定键的前缀
etcdctl get --prefix /test/key /test/key Hello world /test/key2 Hello world2 /test/key3 Hello world3- 限制获取键值对数量
# 只获取key 前缀为 /test/key 的前两个 etcdctl get --prefix --limit=2 /test/key /test/key Hello world /test/key2 Hello world- 获取key的指定过往版本
通过--rev 参数指定获取的key 的历史版本，不指定的话，默认是最新版本
# 获取键的版本信息，rev=53 etcdctl get /test/key --write-out json {"header":{"cluster_id":14841639068965178418,"member_id":10276657743932975437,"revision":53,"raft_term":8},"kvs":[{"key":"L3Rlc3Qva2V5","create_revision":53,"mod_revision":53,"version":1,"value":"SGVsbG8="}],"count":1} # 修改键的值 etcdctl put /test/key Hello world1 # 获取最新的键的版本rev=54 etcdctl get /test/key --write-out json {"header":{"cluster_id":14841639068965178418,"member_id":10276657743932975437,"revision":54,"raft_term":8},"kvs":[{"key":"L3Rlc3Qva2V5","create_revision":53,"mod_revision":54,"version":2,"value":"SGVsbG8="}],"count":1} # 获取指定版本键的值 etcdctl get /test/key --rev=53 /test/key Hello- 读取大于等于指定键的 byte 值的键
假设 etcd 集群已经有下列键：
a=123 b=456 c=789 d=1111 abcsd= 1232312读取大于等于键 c(首字母) 的 byte 值的键的命令：
etcdctl get --from-key c c 789 d 1111通过如下操作指令获取get 操作的详细指令介绍:
etcdctl get -h
-
del
删除某个键etcdctl del test 1返回1 表示删除键成功， 0 表示键不存在
通过如下操作指令获取del 操作的详细指令介绍:etcdctl del -h -
watch
watch用于监听某个键值对并阻塞等待， 一旦键值发生更新，就会输出最新值并返回， 监听可以重复使用，不是只监听一次- 监听某一个键
--hex参数：用于16进制返回
etcdctl watch /test/key # 在另外一个终端: etcdctl put /test/key 111 PUT /test/key 111- 监听范围内的键
# 监听[key ～key3 ）包括key 蛋不包括key3， 左闭右开 etcdctl watch /test/key /test/key33.监听多个键
-i 参数：是指以交互的方式，此时可以输入多个watch key 参数来实现多个键值对监听etcdctl watch -i watch /test/key watch /test/key2 - 监听某一个键
-
lease (租约)
类似于redis 中的TTL（time to live）,通过将键值对绑定到租约上，实现对存活周期的控制， 一旦租约到期，所有被绑定的键都将会被删除- 创建租约
etcdctl lease grant 100 lease 694d7f64201b290a granted with TTL(100s)- 将租约绑定到键上， 注意，租约必须在过期前绑定到键上，不然会报错：
requested lease not found
# 将租约绑定到键上 etcdctl put --lease=694d7f64201b290a /test/lease test OK- 查询租约
# 查询指定租约的信息 etcdctl lease timetolive 694d7f64201b290a lease 694d7f64201b290a granted with TTL(100s), remaining(50s) # 通过加上--keys ，可以查询租约的对应绑定的key etcdctl lease timetolive 694d7f64201b290a lease 694d7f64201b290a granted with TTL(100s), remaining(20s)， attached keys([/test/lease])- 撤销租约
# 撤销租约,此时对应绑定的键值对也会消除 etcdctl lease revoke 694d7f64201b290a lease 694d7f64201b290f revoked #通过get指令找不到原先绑定的键值对 etcdctl get /test/lease- 刷新租约
通过刷新其TTL来保持租约活着，因此不会过期
# 创建20s 的租约 etcdctl lease grant 20 lease 694d7f64201b2918 granted with TTL(20s) # 刷新租约，确保租约不过期 etcdctl lease keep-alive 694d7f64201b2918 lease 694d7f64201b2918 keepalived with TTL(20) lease 694d7f64201b2918 keepalived with TTL(20) -
txn
txn 从标准输入中读取多个请求，将它们看做一个原子性的事务执行。事务是由条件列表，条件判断成功时的执行列表（条件列表中全部条件为真表示成功）和条件判断失败时的执行列表（条件列表中有一个为假即为失败）组成的etcdctl put user frank OK etcdctl txn -i compares: value("user") = "frank" success requests (get, put, del): put result ok failure requests (get, put, del): put result failed SUCCESS OK etcdctl get result result ok解释如下：
- 先使用 etcdctl put user frank 设置 user 为 frank
- etcdctl txn -i 开启事务（-i表示交互模式）
- 第2步输入命令后回车，终端显示出 compares：
- 输入 value("user") = "frank"，此命令是比较 user 的值与 frank 是否相等
- 第 4 步完成后输入回车，终端会换行显示，此时可以继续输入判断条件（前面说过事务由条件列表组成），再次输入回车表示判断条件输入完毕
- 第 5 步连续输入两个回车后，终端显示出 success requests (get, put, delete):，表示下面输入判断条件为真时要执行的命令
与输入判断条件相同，连续两个回车表示成功时的执行列表输入完成 - 终端显示 failure requests (get, put, delete)：后输入条件判断失败时的执行列表
- 为了看起来简洁，此实例中条件列表和执行列表只写了一行命令，实际可以输入多行
- 总结上面的事务，要做的事情就是 user 为 frank 时设置 result 为 ok，否则设置 result 为 failed
- 事务执行完成后查看 result 值为 ok
-
lock
lock 可以通过指定的名字加锁。注意，只有当正常退出且释放锁后，lock命令的退出码是0，否则这个锁会一直被占用创建一个mux1 的锁，并占用锁 etcdctl lock mux1 mux1/41467f68540a4008 #在另一个终端使用mux1 锁，会被阻塞，直到前者释放 etcdctl lock mux1 -
comapct
如我们提到的，etcd 保存修订版本以便应用可以读取键的过往版本。但是，为了避免积累无限数量的历史数据，压缩过往的修订版本就变得很重要。压缩之后，etcd 删除历史修订版本，释放资源来提供未来使用。所有修订版本在压缩修订版本之前的被替代的数据将不可访问etcdctl compact 5 compacted revision 5 #在压缩修订版本之前的任何修订版本都不 可访问
权限控制
ETCD权限控制有两个概念，一个是用户user，另一个是角色 role。用户可以绑定多个角色，
而每个角色对应着多组权限控制，权限包括 读、写、读写
-
role
- 创建role
# 创建test 角色 etcdctl role add test Role test created- 查看role
#查看test 角色 etcdctl role get test Role test KV Read: KV Write: # 列出所有的role etcdctl role list test- 绑定权限
权限：read，write，readwrite
绑定权限需要指定权限的类型，和对应的键， 一个权限可以绑定到多个键上，不会被新的键覆盖
etcdctl put roleTest test #给键roleTest 绑定读写权限的test角色 etcdctl role grant-permission test readwrite roleTest Role test updated # 查看角色 etcdctl role get test Role test KV Read: roleTest KV Write: roleTest- 为角色移除key的权限
为键roleTest 移除test 角色 etcdctl role revoke-permission test roleTest Permission of key roleTest is revoked from role test- 删除role
# 删除test 角色 etcdctl role del test Role test deleted -
user
- 创建用户
创建用户名并输入密码
etcdctl user add u1 Password of u1: Type password of u1 again for confirmation: User u1 created- 查看用户
# 查看用户 etcdctl user get u1 User: u1 Roles: #列出所有用户 etcdctl user list u1- 绑定role
# 创建role etcdctl role add test #将用户u1 绑定test 角色 etcdctl user grant-role u1 test Role test is granted to user u1 # 查看u1 etcdctl user get u1 User: u1 Roles: test- 移除role
etcdctl user revoke-role u1 test Role test is revoked from user u1- 删除用户
# 删除用户不会删除对应绑定的角色 etcdctl user del u1 User u1 deleted - 创建用户
-
auth
etcd 默认是关闭权限认证的， 可以通过如下指令开始和关闭权限认证,当打开权限后，所有的操作，需要加上用户认证
--user=用户名:密码,# 开启权限 etcdctl auth enable #关闭权限 etcdctl auth disable注意
开启权限认证需要先创建root 用户，不然会报如下错误etcdctl auth enable {"level":"warn","ts":"2022-03- 08T11:21:46.782+0800","logger":"etcd-client","caller":"v3/retry_interceptor.go:62","msg":"retrying of unary invoker failed","target":"etcd-endpoints://0xc0001ce000/127.0.0.1:2379","attempt":0,"error":"rpc error: code = FailedPrecondition desc = etcdserver: root user does not exist"} Error: etcdserver: root user does not exist创建root 账号
#创建root角色 etcdctl role add root Role root created #创建root 用户 etcdctl user add root Password of root: Type password of root again for confirmation: User root created #绑定root角色到root 用户 etcdctl user grant-role root root Role root is granted to user root # 开启权限 --user=用户名：密码 etcdctl auth enable --user=root:123456 Authentication Enabled
示例：
etcdctl role add test
etcdctl role grant-permission test readwrite roleTest
etcdctl user add u1
etcdctl user add u2
etcdctl user grant-role u1 test
# root 用户开启权限认证
etcdctl auth enable --user=root:123456
# 查看roleTest， 此时没有权限去查看，需要指定用户
etcdctl get roleTest
{"level":"warn","ts":"2022-03-08T11:35:54.985+0800","logger":"etcd-client","caller":"v3/retry_interceptor.go:62","msg":"retrying of unary invoker failed","target":"etcd-endpoints://0xc0000d2380/127.0.0.1:2379","attempt":0,"error":"rpc error: code = InvalidArgument desc = etcdserver: user name is empty"}
Error: etcdserver: user name is empty
# u2 账号没有绑定对应roleTest键的读写的test role，此时没有权限去查看
etcdctl get roleTest --user=u2:123456
{"level":"warn","ts":"2022-03-08T11:40:32.183+0800","logger":"etcd-client","caller":"v3/retry_interceptor.go:62","msg":"retrying of unary invoker failed","target":"etcd-endpoints://0xc0000e2a80/127.0.0.1:2379","attempt":0,"error":"rpc error: code = PermissionDenied desc = etcdserver: permission denied"}
Error: etcdserver: permission denied
# 通过u1 账号查看
etcdctl get roleTest --user=u1:123456
roleTest
test
集群操作相关
参考 https://www.jianshu.com/p/86c3d5093810集群安装， 三个节点组成集群
endpoints=127.0.0.1:12379,127.0.0.1:22379,127.0.0.1:32379
- 集群成员列表
etcdctl --endpoints=$endpoints member list --write-out table
+------------------+---------+-------+------------------------+------------------------+------------+
| ID | STATUS | NAME | PEER ADDRS | CLIENT ADDRS | IS LEARNER |
+------------------+---------+-------+------------------------+------------------------+------------+
| 8211f1d0f64f3269 | started | test1 | http://127.0.0.1:12380 | http://127.0.0.1:12379 | false |
| 91bc3c398fb3c146 | started | test2 | http://127.0.0.1:22380 | http://127.0.0.1:22379 | false |
| fd422379fda50e48 | started | test3 | http://127.0.0.1:32380 | http://127.0.0.1:32379 | false |
+------------------+---------+-------+------------------------+------------------------+------------+
- 集群成员详细信息
etcdctl --endpoints=$endpoints endpoint status --write-out table
+-----------------+------------------+---------+---------+-----------+------------+-----------+------------+--------------------+--------+
| ENDPOINT | ID | VERSION | DB SIZE | IS LEADER | IS LEARNER | RAFT TERM | RAFT INDEX | RAFT APPLIED INDEX | ERRORS |
+-----------------+------------------+---------+---------+-----------+------------+-----------+------------+--------------------+--------+
| 127.0.0.1:12379 | 8211f1d0f64f3269 | 3.5.2 | 20 kB | true | false | 3 | 27 | 27 | |
| 127.0.0.1:22379 | 91bc3c398fb3c146 | 3.5.2 | 20 kB | false | false | 3 | 27 | 27 | |
| 127.0.0.1:32379 | fd422379fda50e48 | 3.5.2 | 20 kB | false | false | 3 | 27 | 27 | |
+-----------------+------------------+---------+---------+-----------+------------+-----------+------------+--------------------+--------+
- 成员健康状况
etcdctl --endpoints=$endpoints endpoint health --write-out table
+-----------------+--------+------------+-------+
| ENDPOINT | HEALTH | TOOK | ERROR |
+-----------------+--------+------------+-------+
| 127.0.0.1:32379 | true | 6.512053ms | |
| 127.0.0.1:22379 | true | 6.31209ms | |
| 127.0.0.1:12379 | true | 6.648246ms | |
+-----------------+--------+------------+-------+
·
