0 专辑概述
etcd 是云原生架构中重要的根底组件，由 CNCF 孵化托管。etcd 在微服务和 Kubernates 集群中不仅能够作为服务注册与发现，还能够作为 key-value 存储的中间件。

《彻底搞懂 etcd 系列文章》将会从 etcd 的基本功能实际、API 接口、实现原理、源码剖析，以及实现中的踩坑教训等几方面具体开展介绍 etcd。预计会有 20 篇左右的文章，笔者将会每周继续更新，欢送关注。

1 etcdctl 的实际利用
在后面的文章介绍了 etcd 的相干概念，单机和集群的多种装置形式，以及 etcd 平安通信相干的内容。本篇次要基于 etcdctl 介绍 etcd 的常用命令和操作。

etcdctl 是一个命令行客户端，它能提供一些简洁的命令，供用户间接跟 etcd 服务打交道，而无需基于 HTTP API 形式。能够不便咱们在对服务进行测试或者手动批改数据库内容。咱们刚开始能够通过 etdctl 来相熟相干操作。这些操作跟 HTTP API 基本上是对应的。etcdctl 在两个不同的 etcd 版本下的行为形式也齐全不同。

export ETCDCTL_API=2
export ETCDCTL_API=3
这里次要以解说 API 3 为主。

etcd 我的项目二进制发行包中曾经蕴含了 etcdctl 工具，etcdctl 反对的命令大体上分为数据库操作和非数据库操作两类。

2 常用命令介绍
首先查看一下 etcd 的版本：

$ etcd –version

etcd Version: 3.4.7
Git SHA: e784ba73c
Go Version: go1.12.12
Go OS/Arch: linux/amd64
咱们的版本是 etcd 3.4.7，上面介绍下 etcdctl 罕用的命令。

$ etcdctl -h

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

USAGE:
etcdctl [flags]

VERSION:
3.4.7

API VERSION:
3.4
COMMANDS:
alarm disarm Disarms all alarms
alarm list Lists all alarms
auth disable Disables authentication
auth enable Enables authentication
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
migrate Migrates keys in a v2 store to a mvcc store
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 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
  --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)
能够看到，etcdctl 反对的命令很多，罕用的命令选项：

–debug 输入 CURL 命令，显示执行命令的时候发动的申请
–no-sync 发出请求之前不同步集群信息
–output, -o ‘simple’ 输入内容的格局(simple 为原始信息，json 为进行 json 格局解码，易读性好一些)
–peers, -C 指定集群中的伙伴信息，用逗号隔开(默认为: “127.0.0.1:4001”)
–cert-file HTTPS 下客户端应用的 SSL 证书文件
–key-file HTTPS 下客户端应用的 SSL 密钥文件
–ca-file 服务端应用 HTTPS 时，应用 CA 文件进行验证
–help, -h 显示帮忙命令信息
–version, -v 打印版本信息
上面咱们将介绍其中罕用的数据库命令。

3 数据库操作
数据库操作围绕对键值和目录的 CRUD（即增删改查，合乎 REST 格调的一套 API 操作）残缺生命周期的治理。

etcd 在键的组织上采纳了层次化的空间结构(相似于文件系统中目录的概念)，用户指定的键能够为独自的名字，如：testkey，此时实际上放在根目录 / 上面，也能够为指定目录构造，如 /cluster1/node2/testkey，则将创立相应的目录构造。

3.1 键操作
set 指定某个键的值。例如：

$ etcdctl put /testdir/testkey “Hello world”
$ etcdctl put /testdir/testkey2 “Hello world2”
$ etcdctl put /testdir/testkey3 “Hello world3”
胜利写入三对键值，/testdir/testkey、/testdir/testkey2 和 /testdir/testkey3。

get 获取指定键的值。例如：

$ etcdctl get /testdir/testkey
Hello world
get 十六进制读指定的值：

$ etcdctl get /testdir/testkey –hex
\x2f\x74\x65\x73\x74\x64\x69\x72\x2f\x74\x65\x73\x74\x6b\x65\x79 #键
\x48\x65\x6c\x6c\x6f\x20\x77\x6f\x72\x6c\x64 #值
加上 –print-value-only 能够读取对应的值。

get 范畴内的值

$ etcdctl get /testdir/testkey /testdir/testkey3

/testdir/testkey
Hello world
/testdir/testkey2
Hello world2
能够看到，获取了大于等于 /testdir/testkey，且小于 /testdir/testkey3 的键值对。testkey3 不在范畴之内，因为范畴是半开区间 [testkey, testkey3), 不蕴含 testkey3。

获取某个前缀的所有键值对，通过 –prefix 能够指定前缀：

$ etcdctl get –prefix /testdir/testkey
/testdir/testkey
Hello world
/testdir/testkey2
Hello world2
/testdir/testkey3
Hello world3
这样既可获取所有以 /testdir/testkey 结尾的键值对。当前缀获取的后果过多时，还能够通过 –limit=2 限度获取的数量：

etcdctl get –prefix –limit=2 /testdir/testkey
读取键过往版本的值 利用可能想读取键的被代替的值。例如，利用可能想通过拜访键的过往版本来回滚到旧的配置。或者，利用可能想通过多个申请来失去一个笼罩多个键的对立视图，而这些申请能够通过拜访键历史记录而来。因为 etcd 集群上键值存储的每个批改都会减少 etcd 集群的全局订正版本，利用能够通过提供旧有的 etcd 批改版本来读取被代替的键。现有如下这些键值对：

foo = bar # revision = 2
foo1 = bar2 # revision = 3
foo = bar_new # revision = 4
foo1 = bar1_new # revision = 5
以下是拜访以前版本 key 的示例：

$ etcdctl get –prefix foo # 拜访最新版本的 key
foo
bar_new
foo1
bar1_new

$ etcdctl get –prefix –rev=4 foo # 拜访第 4 个版本的 key
foo
bar_new
foo1
bar1

$ etcdctl get –prefix –rev=3 foo # 拜访第 3 个版本的 key
foo
bar
foo1
bar1

$ etcdctl get –prefix –rev=2 foo # 拜访第 3 个版本的 key
foo
bar

$ etcdctl get –prefix –rev=1 foo # 拜访第 1 个版本的 key
读取大于等于指定键的 byte 值的键 利用可能想读取大于等于指定键 的 byte 值的键。假如 etcd 集群曾经有下列键：

a = 123
b = 456
z = 789
读取大于等于键 b 的 byte 值的键的命令：

$ etcdctl get –from-key b
b
456
z
789
删除键。利用能够从 etcd 集群中删除一个键或者特定范畴的键。假如 etcd 集群曾经有下列键：

foo = bar
foo1 = bar1
foo3 = bar3
zoo = val
zoo1 = val1
zoo2 = val2
a = 123
b = 456
z = 789
删除键 foo 的命令：

$ etcdctl del foo
1 # 删除了一个键
删除从 foo to foo9 范畴的键的命令：

$ etcdctl del foo foo9
2 # 删除了两个键
删除键 zoo 并返回被删除的键值对的命令：

$ etcdctl del –prev-kv zoo
1 # 一个键被删除
zoo # 被删除的键
val # 被删除的键的值
删除前缀为 zoo 的键的命令：

$ etcdctl del –prefix zoo
2 # 删除了两个键
删除大于等于键 b 的 byte 值的键的命令：

$ etcdctl del –from-key b
2 # 删除了两个键
3.2 watch 历史改变
watch 监测一个键值的变动，一旦键值产生更新，就会输入最新的值并退出。例如：用户更新 testkey 键值为 Hello watch。

$ etcdctl watch testkey

在另外一个终端: etcdctl put testkey Hello watch

testkey
Hello watch
从 foo to foo9 范畴内键的命令：

$ etcdctl watch foo foo9

在另外一个终端: etcdctl put foo bar

PUT
foo
bar

在另外一个终端: etcdctl put foo1 bar1

PUT
foo1
bar1
以 16 进制格局在键 foo 上进行察看的命令：

$ etcdctl watch foo –hex

在另外一个终端: etcdctl put foo bar

PUT
\x66\x6f\x6f # 键
\x62\x61\x72 # 值
察看多个键 foo 和 zoo 的命令：

$ etcdctl watch -i
$ watch foo
$ watch zoo

在另外一个终端: etcdctl put foo bar

PUT
foo
bar

在另外一个终端: etcdctl put zoo val

PUT
zoo
val
查看 key 的历史改变，利用可能想察看 etcd 中键的历史改变。例如，利用想接管到某个键的所有批改。如果利用始终连贯到 etcd，那么 watch 就足够好了。然而，如果利用或者 etcd 出错，改变可能产生在出错期间，这样利用就没能实时接管到这个更新。为了保障更新被交付，利用必须可能察看到键的历史变动。为了做到这点，利用能够在察看时指定一个历史订正版本，就像读取键的过往版本一样。
假如咱们实现了下列操作序列：

$ etcdctl put foo bar # revision = 2
OK
$ etcdctl put foo1 bar1 # revision = 3
OK
$ etcdctl put foo bar_new # revision = 4
OK
$ etcdctl put foo1 bar1_new # revision = 5
OK
察看历史改变：

从订正版本 2 开始察看键 foo 的改变

$ etcdctl watch –rev=2 foo
PUT
foo
bar
PUT
foo
bar_new
从上一次历史批改开始察看：

在键 foo 上察看变更并返回被批改的值和上个订正版本的值

$ etcdctl watch –prev-kv foo

在另外一个终端: etcdctl put foo bar_latest

PUT
foo # 键
bar_new # 在批改前键 foo 的上一个值
foo # 键
bar_latest # 批改后键 foo 的值
压缩订正版本。如咱们提到的，etcd 保留订正版本以便利用能够读取键的过往版本。然而，为了防止积攒有限数量的历史数据，压缩过往的订正版本就变得很重要。压缩之后，etcd 删除历史订正版本，开释资源来提供将来应用。所有订正版本在压缩订正版本之前的被代替的数据将不可拜访。这是压缩订正版本的命令：

$ etcdctl compact 5
compacted revision 5 #在压缩订正版本之前的任何订正版本都不可拜访
$ etcdctl get –rev=4 foo
{“level”:”warn”,”ts”:”2020-05-04T16:37:38.020+0800″,”caller”:”clientv3/retry_interceptor.go:62″,”msg”:”retrying of unary invoker failed”,”target”:”endpoint://client-c0d35565-0584-4c07-bfeb-034773278656/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
3.3 租约
授予租约 利用能够为 etcd 集群外面的键授予租约。当键被附加到租约时，它的存活工夫被绑定到租约的存活工夫，而租约的存活工夫相应的被 time-to-live (TTL)治理。在租约授予时每个租约的最小 TTL 值由利用指定。租约的理论 TTL 值是不低于最小 TTL，由 etcd 集群抉择。一旦租约的 TTL 到期，租约就过期并且所有附带的键都将被删除。

授予租约，TTL 为 100 秒

$ etcdctl lease grant 100
lease 694d71ddacfda227 granted with TTL(10s)

附加键 foo 到租约 694d71ddacfda227

$ etcdctl put –lease=694d71ddacfda227 foo10 bar
OK
倡议工夫设置久一点，否则来不及操作会呈现如下的谬误：

撤销租约 利用通过租约 id 能够撤销租约。撤销租约将删除所有它附带的 key。假如咱们实现了下列的操作：

$ etcdctl lease revoke 694d71ddacfda227
lease 694d71ddacfda227 revoked

$ etcdctl get foo10
刷新租期
应用程序能够通过刷新其 TTL 来放弃租约活着，因而不会过期。

$ etcdctl lease keep-alive 694d71ddacfda227
lease 694d71ddacfda227 keepalived with TTL(100)
lease 694d71ddacfda227 keepalived with TTL(100)
…
查问租期 应用程序可能想要理解租赁信息，以便它们能够续订或查看租赁是否依然存在或已过期。应用程序也可能想晓得特定租约所附的 key。

假如咱们实现了以下一系列操作：

$ etcdctl lease grant 300
lease 694d71ddacfda22c granted with TTL(300s)

$ etcdctl put –lease=694d71ddacfda22c foo10 bar
OK
获取无关租赁信息以及哪些 key 应用了租赁信息：

$ etcdctl lease timetolive 694d71ddacfda22c
lease 694d71ddacfda22c granted with TTL(300s), remaining(282s)

$ etcdctl lease timetolive –keys 694d71ddacfda22c
lease 694d71ddacfda22c granted with TTL(300s), remaining(220s), attached keys([foo10])
4 小结
本篇次要基于 etcdctl 介绍 etcd 的常用命令和操作，包含键值对的操作、租期、Watch 监测键值等。通过这些命令实现咱们在后面文章介绍的 etcd 多种应用场景。