etcdctl v2 v3

etcd2和etcd3是不兼容的，两者的api参数也不一样，详细请查看 etcdctl -h 。 可以使用api2 和 api3 写入 etcd3 数据，但是需要注意，使用不同的api版本写入数据需要使用相应的api版本读取数据。

默认，为了向后兼容 etcdctl 使用 v2 API 来和 etcd 服务器通讯。为了让 etcdctl 使用 v3 API 来和etcd通讯，API 版本必须通过环境变量 ETCDCTL_API 设置为版本3。

ETCDCTL_API=2

缺省使用 ETCDCTL_API=2

 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

[root@vStack etcd-v3.0.15-linux-amd64]# ./etcdctl help
NAME:
　　etcdctl - A simple command line client for etcd.

USAGE:
　　etcdctl [global options] command [command options] [arguments...]

VERSION:
　　3.0.15

COMMANDS:
　　1. backup 　　　　　　　　 　　 　　 backup an etcd directory
　　2. cluster-health 　　　　　　　　　　check the health of the etcd cluster
　　3. mk 　　　　　　　　　　　　　　　 make a new key with a given value
　　4. mkdir 　　　　　　　　　　　　　　make a new directory
　　5. rm 　　　　　　　　　　　　　　　 remove a key or a directory
　　6. rmdir 　　　　　　　　　　　　　　removes the key if it is an empty directory or a key-value pair
　　7. get 　　　　　　　　　　　　　　   retrieve the value of a key
　　8. ls 　　　　　　　　　　　　　　　　retrieve a directory
　　9. set 　　　　　  　　　　　　　　　 set the value of a key
　　10. setdir 　　　　　　　　　　　　　create a new directory or update an existing directory TTL
　　11. update 　　　　　　　　　　　    update an existing key with a given value
　　12. updatedir 　　　　　　　　　　   update an existing directory
　　13. watch 　　　　　　　　　　　　  watch a key for changes
　　14. exec-watch 　　　　　　　　　　watch a key for changes and exec an executable
　　15. member 　　　　　　　　　　     member add, remove and list subcommands
　　16. import 　　　　　　　 　　　　　 import a snapshot to a cluster
　　17. user 　　　　　　　　　　　　　  user add, grant and revoke subcommands
　　18. role 　　　　　　　　　　　　　　role add, grant and revoke subcommands
　　19. auth 　　　　　　　　　　　　　 overall auth controls

GLOBAL OPTIONS:
--debug 　　　　　　　　　　　　　　　　　　 output cURL commands which can be used to reproduce the request
--no-sync 　　　　　　　　　　　　　　　　    don't synchronize cluster information before sending request
--output simple, -o simple 　　　　　　　　   output response in the given format (simple, `extended` or `json`) (default: "simple")
--discovery-srv value, -D value 　　　　　　  domain name to query for SRV records describing cluster endpoints
--insecure-discovery 　　　　　　　　　　　　accept insecure SRV records describing cluster endpoints
--peers value, -C value 　　　　　　　　　　  DEPRECATED - "--endpoints" should be used instead
--endpoint value 　　　　　　　　　　　　　　DEPRECATED - "--endpoints" should be used instead
--endpoints value 　　　　　　　　　　　　　 a comma-delimited list of machine addresses in the cluster (default: "http://127.0.0.1:2379,http://127.0.0.1:4001")
--cert-file value 　　　　　　　　　　　　　　  identify HTTPS client using this SSL certificate file
--key-file value 　　　　　　　　　　　　　　   identify HTTPS client using this SSL key file
--ca-file value 　　　　　　　　　　　　　　　  verify certificates of HTTPS-enabled servers using this CA bundle
--username value, -u value 　　　　　　　　   provide username[:password] and prompt if password is not supplied.
--timeout value 　　　　　　　　　　　　　　  connection timeout per request (default: 1s)
--total-timeout value 　　　　　　　　　　　　timeout for the command execution (except watch) (default: 5s)
--help, -h 　　　　　　　　　　　　　　　　     show help
--version, -v 　　　　　　　　　　　　　　　　 print the version

ETCDCTL_API=3

 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
86
87
88

 export ETCDCTL_API=3

[root@vStack etcd-v3.0.15-linux-amd64]# ./etcdctl --help

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

USAGE:
　　etcdctl

VERSION:
　　3.0.15

COMMANDS:
　　1. get	　　　　　　　　　　　　Gets the key or a range of keys

　　　　　　etcdctl get [options] <key> [range_end]

　　　　　　OPTIONS:

　　　　　　　　--consistency="l"	　　　　　　	Linearizable(l) or Serializable(s)
　　　　　　　　--from-key[=false]	　　　　　  Get keys that are greater than or equal to the given key
　　　　　　　　--keys-only[=false]	　　　　　 Get only the keys
　　　　　　　　--limit=0	　　　　　　　　　　  Maximum number of results
　　　　　　　　--order=""	　　　　　　　　　　Order of results; ASCEND or DESCEND
　　　　　　　　--prefix[=false]	　　　　　　　  Get keys with matching prefix
　　　　　　　　--rev=0	　　　　　　　　　　   	Specify the kv revision
　　　　　　　　--sort-by=""	　　　　　　　　  	Sort target; CREATE, KEY, MODIFY, VALUE, or VERSION


　　2. put	　　　　　　　　　　　　Puts the given key into the store
　　3. del	　　　　　　　　	　　　　Removes the specified key or range of keys [key, range_end)
　　4. txn	　　　　　　　　　　　　Txn processes all the requests in one transaction
　　5. compaction	　　　　　　 　  Compacts the event history in etcd  。 etcd支持历史数据的读取，为了避免积累无限历史数据。compacting操作后，etcd将删除历史的版本数据，释放资源为后面使用。在compacted 版本前的数据都将无效。




　　6. alarm disarm	　　　 　　　　Disarms all alarms
　　7. alarm list	　　　　　 　　　　Lists all alarms
　　8. defrag	　　　　　　 	　　　　Defragments the storage of the etcd members with given endpoints
　　9. endpoint health	　　　　　　Checks the healthiness of endpoints specified in `--endpoints` flag
　　10. endpoint status	　　	　　  Prints out the status of endpoints specified in `--endpoints` flag
　　11. watch	　　　　　　　　　　 Watches events stream on keys or prefixes
　　12. version	　　　　　　　　    Prints the version of etcdctl
　　13. lease grant	　　　　　　　  Creates leases
　　14. lease revoke	　　　　　　 	Revokes leases
　　15. lease keep-alive	　　　　　Keeps leases alive (renew)
　　16. member add	　　　　　　  Adds a member into the cluster
　　17. member remove	　　　　 	Removes a member from the cluster
　　18. member update	　　　　  	Updates a member in the cluster
　　19. member list	　　　　　　  	Lists all members in the cluster
　　20. snapshot save	　　　　　  Stores an etcd node backend snapshot to a given file
　　21. snapshot restore	　　　　 Restores an etcd member snapshot to an etcd directory
　　22. snapshot status	　　　　 	Gets backend snapshot status of a given file
　　23. make-mirror	　　　　　　  Makes a mirror at the destination etcd cluster
　　24. migrate	　　　　　　　　 　Migrates keys in a v2 store to a mvcc store
　　25. lock	　　　　　　　　　　   Acquires a named lock
　　26. elect	　　　　　　　　　　 	Observes and participates in leader election
　　27. auth enable	　　　　　　  	Enables authentication
　　28. auth disable	　　　　　　 	Disables authentication
　　29. user add	　　　　　　　　	Adds a new user
　　30. user delete	　　　　　　　 Deletes a user
　　31. user get	　　　　　　　　 	Gets detailed information of a user
　　32. user list	　　　　　　　　 	Lists all users
　　33. user passwd	　　　　　　	Changes password of user
　　34. user grant-role	　　　　　 Grants a role to a user
　　35. user revoke-role	　　　　 Revokes a role from a user
　　36. role add	　　　　　　　　 	Adds a new role
　　37. role delete	　　　　　　    	Deletes a role
　　38. role get	　　　　　　　　  	Gets detailed information of a role
　　39. role list	　　　　　　　　　 Lists all roles
　　40. role grant-permission	　　Grants a key to a role
　　41. role revoke-permission	　 Revokes a key from a role
　　42. help	　　	　　　　　　　　 Help about any command

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)
　　--dial-timeout=2s	　　　　　　　　　　   	dial timeout for client connections
　　--endpoints=[127.0.0.1:2379]	　　　　   gRPC endpoints
　　--hex[=false]	　　　　　　　　　　　　　   print byte strings as hex encoded strings
　　--insecure-skip-tls-verify[=false]	　　　　skip server certificate verification
　　--insecure-transport[=true]	　　　　　　	disable transport security for client connections
　　--key=""	　　　　　　　　　　　　　　　　	identify secure client using this TLS key file
　　--user=""	　　　　　　　　　　　　　　　  username[:password] for authentication (prompt if password is not supplied)
　　-w, --write-out="simple"	　　　　　　　　	set the output format (simple, json, etc..)

常用命令

增删改查

增

1

etcdctl --endpoints=$ENDPOINTS put foo "Hello World!"

查

1
2

etcdctl --endpoints=$ENDPOINTS get foo
etcdctl --endpoints=$ENDPOINTS --write-out="json" get foo

基于相同前缀查找

1
2
3
4
5

etcdctl --endpoints=$ENDPOINTS put web1 value1
etcdctl --endpoints=$ENDPOINTS put web2 value2
etcdctl --endpoints=$ENDPOINTS put web3 value3

etcdctl --endpoints=$ENDPOINTS get web --prefix

删

1
2
3
4
5
6

etcdctl --endpoints=$ENDPOINTS put key myvalue
etcdctl --endpoints=$ENDPOINTS del key

etcdctl --endpoints=$ENDPOINTS put k1 value1
etcdctl --endpoints=$ENDPOINTS put k2 value2
etcdctl --endpoints=$ENDPOINTS del k --prefix

集群状态

集群状态主要是etcdctl endpoint status 和etcdctl endpoint health两条命令。

1
2
3
4
5
6
7
8
9

etcdctl --write-out=table --endpoints=$ENDPOINTS endpoint status

+------------------+------------------+---------+---------+-----------+-----------+------------+
|     ENDPOINT     |        ID        | VERSION | DB SIZE | IS LEADER | RAFT TERM | RAFT INDEX |
+------------------+------------------+---------+---------+-----------+-----------+------------+
| 10.240.0.17:2379 | 4917a7ab173fabe7 | 3.0.0   | 45 kB   | true      |         4 |      16726 |
| 10.240.0.18:2379 | 59796ba9cd1bcd72 | 3.0.0   | 45 kB   | false     |         4 |      16726 |
| 10.240.0.19:2379 | 94df724b66343e6c | 3.0.0   | 45 kB   | false     |         4 |      16726 |
+------------------+------------------+---------+---------+-----------+-----------+------------+

1
2
3
4
5

etcdctl --endpoints=$ENDPOINTS endpoint health

10.240.0.17:2379 is healthy: successfully committed proposal: took = 3.345431ms
10.240.0.19:2379 is healthy: successfully committed proposal: took = 3.767967ms
10.240.0.18:2379 is healthy: successfully committed proposal: took = 4.025451ms

集群成员

跟集群成员相关的命令如下：

1
2
3
4

    member add          Adds a member into the cluster
    member remove       Removes a member from the cluster
    member update       Updates a member in the cluster
    member list         Lists all members in the cluster

例如 etcdctl member list列出集群成员的命令。

1
2
3
4
5
6
7
8

etcdctl --endpoints=http://172.16.5.4:12379 member list -w table

+-----------------+---------+-------+------------------------+-----------------------------------------------+
|       ID        | STATUS  | NAME  |       PEER ADDRS       |                 CLIENT ADDRS                  |
+-----------------+---------+-------+------------------------+-----------------------------------------------+
| c856d92a82ba66a | started | etcd0 | http://172.16.5.4:2380 | http://172.16.5.4:2379,http://172.16.5.4:4001 |
+-----------------+---------+-------+------------------------+-----------------------------------------------+
---------------------

身份验证

etcd 默认是没有开启访问控制的，如果我们开启外网访问的话就需要考虑访问控制的问题，etcd 提供了两种访问控制的方式：

  1. 基于身份验证的访问控制
  2. 基于证书的访问控制

这节主要是选择第一种方式，进行的讲解.

root 用户

root 是 etcd 的超级管理员，拥有 etcd 的所有权限，在开启角色认证之前为们必须要先建立好 root 用户。还需要注意的是 root 用户必须拥有 root 的角色,允许在 etcd 的所有操作.

root 角色

root 角色可以赋予任何用户，拥有 root 角色的用户有全局读写权限和集群身份验证配置权限，此外，还具有修改集群成员身份，碎片整理，建立快照等权限。

用户操作

查看用户列表：

1

etcdctl --ca-file /root/cfssl/ca.pem --endpoints https://192.168.3.3:2379 user list

创建用户：

1

 etcdctl --ca-file /root/cfssl/ca.pem --endpoints https://192.168.3.3:2379 user add user1

用户可以被赋予角色，也可以被撤销角色：

赋予权限:

1

etcdctl --ca-file /root/cfssl/ca.pem --endpoints https://192.168.3.3:2379 user grant --roles root user1

撤销权限:

1

etcdctl --ca-file /root/cfssl/ca.pem --endpoints https://192.168.3.3:2379 user revoke --roles root user1

修改用户密码：

1

etcdctl --ca-file /root/cfssl/ca.pem --endpoints https://192.168.3.3:2379 user passwd user1

角色操作

角色列表:

1

etcdctl --ca-file /root/cfssl/ca.pem --endpoints https://192.168.3.3:2379 role list

创建角色:

1

etcdctl --ca-file /root/cfssl/ca.pem --endpoints https://192.168.3.3:2379 role add myrolename

角色没有密码，仅仅是定义的一组访问权限

角色的访问权限可以被赋予read（读）,write（写）,readwrite（读和写）权限

赋予访问权限范例：

给 role1 角色赋予键 /foo 的读操作

1

etcdctl --ca-file /root/cfssl/ca.pem --endpoints https://192.168.3.3:2379 role grant role1 --path /foo --read

给 role1 角色赋予键 /foo 的写操作

1

etcdctl --ca-file /root/cfssl/ca.pem --endpoints https://192.168.3.3:2379 role grant role1 --path /foo --write

给 role1 角色赋予键 /foo 读写操作

1

etcdctl --ca-file /root/cfssl/ca.pem --endpoints https://192.168.3.3:2379 role grant role1 --path /foo --rw

给 role1 角色赋予键 /foo 目录读写操作

1

etcdctl --ca-file /root/cfssl/ca.pem --endpoints https://192.168.3.3:2379 role grant role1 --path /foo/* --rw

收回访问权限范例：

收回 role1 角色对 /foo 的读操作

1

etcdctl --ca-file /root/cfssl/ca.pem --endpoints https://192.168.3.3:2379 role revoke role1 --path /foo --read

收回 role1 角色对 /foo 的写操作

1

etcdctl --ca-file /root/cfssl/ca.pem --endpoints https://192.168.3.3:2379 role revoke role1 --path /foo --write

收回 role1 角色对 /foo 的读写操作

1

etcdctl --ca-file /root/cfssl/ca.pem --endpoints https://192.168.3.3:2379 role revoke role1 --path /foo --rw

收回 role1 角色对 /foo 目录的读写操作

1

etcdctl --ca-file /root/cfssl/ca.pem --endpoints https://192.168.3.3:2379 role revoke role1 --path /foo/* --rw

查看角色访问权限:

1

etcdctl --ca-file /root/cfssl/ca.pem --endpoints https://192.168.3.3:2379 role get role1

删除角色 :

1

etcdctl --ca-file /root/cfssl/ca.pem --endpoints https://192.168.3.3:2379 role remove role1

开启身份验证

1.增加root用户:

1
2

$ etcdctl --ca-file /root/cfssl/ca.pem --endpoints https://192.168.3.3:2379 user add root
Password of root:

2.开启身份验证:

1

etcdctl --ca-file /root/cfssl/ca.pem --endpoints https://192.168.3.3:2379 etcdctl auth enable

至此，身份验证已经开启，执行下面命令

1
2

etcdctl --ca-file /root/cfssl/ca.pem  --endpoints https://192.168.3.3:2379 set /foo bar
//返回bar

这里出现了一个问题，我们已经开启了身份访问验证，却仍然可以不通过任何身份进行操作，这是什么原因呢？其实是因为在 Etcd 开启 Basic Auth 之后，默认会启用两个角色 root 和 guest， root 和 guest 角色都拥有所有权限，当我们未指定身份的时候其实是通过 guest 角色进行的操作，这里需要注意的是两个角色都不要删除，否则你可能会遇到意想不到的Bug，既然无法删除，那么为们可以通过收回权限的方式对 guest 的权限进行限制，执行下面代码：

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

etcdctl --ca-file /root/cfssl/ca.pem --username root:passwod --endpoints https://192.168.3.3:2379 ro
le revoke guest --path '/*' --rw

//返回：Role guest updated

//查看guest最新的权限信息
etcdctl --ca-file /root/cfssl/ca.pem --username root:passwod --endpoints https://192.168.3.3:2379 ro
le get guest


//返回 ：
 //       Role: guest
//        KV Read:
//        KV Write:
// ok 收回权限成功

继续执行之前的set代码 ：

1
2

etcdctl --ca-file /root/cfssl/ca.pem  --endpoints https://192.168.3.3:2379 set /foo bar
//Error:  110: The request requires user authentication (Insufficient credentials) [0]

如我们所愿的已经不可以对 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

# 创建user2用户
etcdctl --ca-file /root/cfssl/ca.pem --username root:passwod --endpoints https://192.168.3.3:2379 user add user2

New password:
//返回 ：User user2 created

# 创建role2角色
etcdctl --ca-file /root/cfssl/ca.pem --username root:passwod --endpoints https://192.168.3.3:2379 role add role2

Role role2 created

# 赋予role2 角色权限

etcdctl --ca-file /root/cfssl/ca.pem --username root:passwod --endpoints https://192.168.3.3:2379 ro
le grant role2 --path /foo --rw
Role role2 updated


# 将用户user2赋予角色role2
etcdctl --ca-file /root/cfssl/ca.pem --username root:passwod --endpoints https://192.168.3.3:2379 us
er  grant --roles role2 user2

User user2 updated

# 设置 foo 值
etcdctl --ca-file /root/cfssl/ca.pem --username user2:passwod --endpoints https://192.168.3.3:2379:2379 set foo bar

bar

参考:
https://blog.csdn.net/huwh_/article/details/80225902
https://blog.csdn.net/kozazyh/article/details/79586530
https://blog.csdn.net/huwh_/article/details/80225902
http://www.artacode.com/posts/etcd/auth/