(一) etcd3-server-API-原创手记-慕课网

etcd3项目分为两部分，一是etcd clientv3，一是etcd3 server。etcd3与etcd2是不同的代码实现，同时etcd3 server支持etcd2 api，但是数据不是共用的，V2和V3 server分别独立维护自己的数据。
etcd clientv3是将对V3 server的grpc请求封装成go packge供go程序员调用的库。
本文旨在概述etcd3 的grpc API，所有代码协议均是grpc。

(一) etcd3 gRPC API概述

发送到etcd服务器的每个API请求都是gRPC远程过程调用。etcd3中的RPC根据功能分类为：

1、处理etcd key空间的API包括：

KV - 创建，更新，提取和删除key-value对。
Watch - 监视对key的更改。
Lease - 指定时间（秒）的TTL，用于关联多个key。

2、管理集群本身的API包括：

Auth - 基于角色的身份验证机制，用于验证用户身份。
Cluster - 提供集群成员信息和配置方法。
Maintenance - 获取恢复快照，维护人员用于恢复。

1.1 Request和Response

etcd3中的所有gRPC都遵循相同的格式。每个gRPC都有一个函数Name，该函数NameRequest作为参数并NameResponse作为响应返回。详细gRPC API描述：

service KV {
            /* Range gets the keys in the range from the key-value store. */
            Range (RangeRequest) returns (RangeResponse)
          /* Put puts the given key into the key-value store. A put request increments the revision of the key-value store and generates one event in the event history.*/
            Put (PutRequest) returns (PutResponse)
            /* DeleteRange deletes the given range from the key-value store. A delete request increments the revision of the key-value store and generates a delete event in the event history for every deleted key.*/
            DeleteRange (DeleteRangeRequest) returns (DeleteRangeResponse)
/* Txn processes multiple requests in a single transaction. A txn request increments the revision of the key-value store and generates events with the same revision for every completed request. It is not allowed to modify the same key several times within one txn.*/
            Txn (TxnRequest) returns (TxnResponse)
          /* Compact compacts the event history in the etcd key-value store. The key-value store should be periodically compacted or the event history will continue to grow indefinitely.*/
          Compact (CompactionRequest) returns (CompactionResponse)
}
service Watch {
          /* Watch watches for events happening or that have happened. Both input and output are streams; the input stream is for creating and canceling watchers and the output stream sends events. One watch RPC can watch on multiple key ranges, streaming events for several watches at once. The entire event history can be watched starting from the last compaction revision.*/
            Watch (stream WatchRequest) returns (stream WatchResponse)
}
service Lease {
/*  LeaseGrant creates a lease which expires if the server does not receive a keepAlive within a given time to live period. All keys attached to the lease will be expired and deleted if the lease expires. Each expired key generates a delete event in the event history.*/
            LeaseGrant (LeaseGrantRequest) returns (LeaseGrantResponse)
          /* LeaseRevoke revokes a lease. All keys attached to the lease will expire and be deleted. */
            LeaseRevoke (LeaseRevokeRequest) returns (LeaseRevokeResponse)
          /* LeaseKeepAlive keeps the lease alive by streaming keep alive requests from the client to the server and streaming keep alive responses from the server to the client. */
            LeaseKeepAlive (stream LeaseKeepAliveRequest) returns (stream LeaseKeepAliveResponse)
/* LeaseTimeToLive retrieves lease information. */
            LeaseTimeToLive (LeaseTimeToLiveRequest) returns (LeaseTimeToLiveResponse)
/* LeaseLeases lists all existing leases. */
            LeaseLeases (LeaseLeasesRequest) returns (LeaseLeasesResponse)
}
service Auth {
/* AuthEnable enables authentication. */
            AuthEnable (AuthEnableRequest) returns (AuthEnableResponse)
/* AuthDisable disables authentication. */
            AuthDisable (AuthDisableRequest) returns (AuthDisableResponse)
/* Authenticate processes an authenticate request. */
            Authenticate (AuthenticateRequest) returns (AuthenticateResponse)
/* UserAdd adds a new user. */
            UserAdd(AuthUserAddRequest) returns (AuthUserAddResponse)
/* UserGet gets detailed user information.*/
            UserGet(AuthUserGetRequest) returns (AuthUserGetResponse)
/* UserList gets a list of all users.*/
            UserList(AuthUserListRequest) returns (AuthUserListResponse)
/* UserDelete deletes a specified user. */
          UserDelete(AuthUserDeleteRequest) returns (AuthUserDeleteResponse)
/* UserChangePassword changes the password of a specified user.*/
            UserChangePassword(AuthUserChangePasswordRequest) returns (AuthUserChangePasswordResponse)
/* UserGrant grants a role to a specified user. */
            UserGrantRole(AuthUserGrantRoleRequest) returns (AuthUserGrantRoleResponse)
/* UserRevokeRole revokes a role of specified user.*/
            UserRevokeRole(AuthUserRevokeRoleRequest) returns (AuthUserRevokeRoleResponse)
/* RoleAdd adds a new role. */
            RoleAdd(AuthRoleAddRequest) returns (AuthRoleAddResponse)
/* RoleGet gets detailed role information. */
            RoleGet(AuthRoleGetRequest) returns (AuthRoleGetResponse)
/* RoleList gets lists of all roles.*/
            RoleList(AuthRoleListRequest) returns (AuthRoleListResponse)
/* RoleDelete deletes a specified role.*/
            RoleDelete(AuthRoleDeleteRequest) returns (AuthRoleDeleteResponse)
/* RoleGrantPermission grants a permission of a specified key or range to a specified role.*/
            RoleGrantPermission(AuthRoleGrantPermissionRequest) returns (AuthRoleGrantPermissionResponse)
/* RoleRevokePermission revokes a key or range permission of a specified role. */
RoleRevokePermission(AuthRoleRevokePermissionRequest) returns (AuthRoleRevokePermissionResponse)
}
service Cluster {
/* MemberAdd adds a member into the cluster.*/
            MemberAdd(MemberAddRequest) returns (MemberAddResponse)
/* MemberRemove removes an existing member from the cluster. */
            MemberRemove(MemberRemoveRequest) returns (MemberRemoveResponse)
/* MemberUpdate updates the member configuration. */
            MemberUpdate(MemberUpdateRequest) returns (MemberUpdateResponse)
/* MemberList lists all the members in the cluster. */
            MemberList(MemberListRequest) returns (MemberListResponse)
}
service Maintenance {
/* Alarm activates, deactivates, and queries alarms regarding cluster health. */
            Alarm(AlarmRequest) returns (AlarmResponse)
/* Status gets the status of the member. */
            Status(StatusRequest) returns (StatusResponse)
/* Defragment defragments a member's backend database to recover storage space. */
            Defragment(DefragmentRequest) returns (DefragmentResponse)
/* Hash computes the hash of whole backend keyspace, including key, lease, and other buckets in storage. This is designed for testing ONLY! Do not rely on this in production with ongoing transactions, since Hash operation does not hold MVCC locks. Use "HashKV" API instead for "key" bucket consistency checks. */
            Hash(HashRequest) returns (HashResponse)
/* HashKV computes the hash of all MVCC keys up to a given revision. It only iterates "key" bucket in backend storage.*/
            HashKV(HashKVRequest) returns (HashKVResponse)
/* Snapshot sends a snapshot of the entire backend from a member over a stream to a client. */
            Snapshot(SnapshotRequest) returns (stream SnapshotResponse)
/* MoveLeader requests current leader node to transfer its leadership to transferee. */
            MoveLeader(MoveLeaderRequest) returns (MoveLeaderResponse)
}

1.2 Response Header

来自etcd API的所有响应都有一个附加的响应头，其中包含响应的集群元数据：

message ResponseHeader {
      /* cluster_id is the ID of the cluster which sent the response. */
        uint64 cluster_id=1;
       /* member_id is the ID of the member which sent the response. */
        uint64 member_id=2;
       /* revision is the key-value store revision when the request was applied. For watch progress responses, the header.revision indicates progress. All future events recieved in this stream are guaranteed to have a higher revision number than the header.revision number. */
        int64 revision=3;
/* raft_term is the raft term when the request was applied. */
        uint64 raft_term=4;
}

Cluster_ID - 生成响应的集群的ID。

Member_ID - 生成响应的成员的ID。

Reversion - 生成响应时key-value存储的修订版。

Raft_Term - 生成响应时成员的Raft术语。

(二) KV API

2.1 Key-Value

Key-Value是KV API可以操作的最小单位。每个key-value对都有许多以protobuf格式定义的字段：

message KeyValue {
       /* key is the key in bytes. An empty key is not allowed.  */
        bytes    key=1;
      /* create_revision is the revision of last creation on this key.  */
        int64    create_revision=2;
        /* mod_revision is the revision of last modification on this key.  */
        int64    mod_revision=3;
       /* version is the version of the key. A deletion resets the version to zero and any modification of the key increases its version. */
        int64    version=4;
       /* value is the value held by the key, in bytes.  */
        bytes    value=5;
       /* lease is the ID of the lease that attached to key. When the attached lease expires, the key will be deleted. If lease is 0, then no lease is attached to the key.  */
        int64    lease=6;
}

Key --- 以字节为单位的key，不允许使用空ke'y。

Value --- 以字节为单位的value。

Version --- 版本是key的版本。删除version将重置为零，并且对key的任何修改都会增加其版本。

Create_Revision --- 最后一次创建key的版本号。

Mod_Revision --- 最后一次修改key的版本号。

Lease --- 附加到key的Lease的ID。如果Lease为0，表明没有将任何Lease附加到key。

2.2 Range Request

使用Range API调用从KV存储中获取key，其中包含RangeRequest：

message RangeRequest {
enum SortOrder {
        NONE = 0; // default, no sorting
        ASCEND = 1; // lowest target value first
        DESCEND = 2; // highest target value first
}
enum SortTarget {
        KEY = 0;
        VERSION = 1;
        CREATE = 2;
        MOD = 3;
        VALUE = 4;
}
/* key is the first key for the range. If range_end is not given, the request only looks up key. */
bytes key = 1;
/* range_end is the upper bound on the requested range [key, range_end). If range_end is '\0', the range is all keys >= key. If range_end is key plus one (e.g., "aa"+1 == "ab", "a\xff"+1 == "b"), then the range request gets all keys prefixed with key. If both key and range_end are '\0', then the range request returns all keys. */
bytes range_end = 2;
/* limit is a limit on the number of keys returned for the request. When limit is set to 0, it is treated as no limit. */
int64 limit = 3;
/* revision is the point-in-time of the key-value store to use for the range. If revision is less or equal to zero, the range is over the newest key-value store. If the revision has been compacted, ErrCompacted is returned as a response. */
int64     revision = 4;
/* sort_order is the order for returned sorted results. */
SortOrder     sort_order = 5;
/* sort_target is the key-value field to use for sorting. */
SortTarget     sort_target = 6;
/* serializable sets the range request to use serializable member-local reads. Range requests are linearizable by default; linearizable requests have higher latency and lower throughput than serializable requests but reflect the current consensus of the cluster. For better performance, in exchange for possible stale reads, a serializable range request is served locally without needing to reach consensus with other nodes in the cluster. */
bool     serializable = 7;
/*  keys_only when set returns only the keys and not the values. */
bool     keys_only = 8;
/* count_only when set returns only the count of the keys in the range. */
bool     count_only = 9;
/*  min_mod_revision is the lower bound for returned key mod revisions; all keys with lesser mod revisions will be filtered away. */
int64     min_mod_revision = 10;
/* max_mod_revision is the upper bound for returned key mod revisions; all keys with greater mod revisions will be filtered away. */
int64     max_mod_revision = 11;
/* min_create_revision is the lower bound for returned key create revisions; all keys with lesser create revisions will be filtered away. */
int64     min_create_revision = 12;
/* max_create_revision is the upper bound for returned key create revisions; all keys with greater create revisions will be filtered away. */
int64     max_create_revision = 13;
}

Key，Range_End --- 要获取的key范围。

Limit ---限制请求返回的最大key数量。当limit设置为0时，将其视为无限制。

Revision --- 用于key Range内的KV存储的版本范围限制。如果revision小于或等于零，则范围超过最新的key-value存储如果压缩修订，则返回ErrCompacted作为响应。

Sort_Order --- 请求倒序还是顺序。

Sort_Target --- 要排序的类型（key, value, version, create_version, mod_version）。

Serializable --- 设置范围请求以使用可序列化的成员本地读取。默认情况下，Range是可线性化的; 它反映了该集群目前的共识。为了获得更好的性能和可用性，为了换取可能的过时读取，可在本地提供可序列化范围请求，而无需与群集中的其他节点达成共识。

Keys_Only --- 仅返回key而不返回value。

Count_Only --- 仅返回range中key的计数。

Min_Mod_Revision --- key mod version的下限;

Max_Mod_Revision --- key mod version的上限;

Min_Create_Revision --- key create version的下限;

Max_Create_Revision --- key create version的上限;

2.3 Range Response：

message    RangeResponse {
    ResponseHeader    header=1;
/* kvs is the list of key-value pairs matched by the range request. kvs is empty when count is requested. */
    repeated KeyValue    kvs=2;
/* more indicates if there are more keys to return in the requested range. */
    bool    more=3;
/* count is set to the number of keys within the range when requested. */
    int64    count=4;
}

Header ---见ResponseHeader

Kvs --- 范围请求匹配的key-value对列表。当Count_Only设置为true时，Kvs为空。

More --- 表明RangeRequest中的limit为true。

Count --- 满足范围请求的key总数。

2.4 Put Request

通过发出Put Request将key-value保存到KV存储中：

message    PutRequest {
/* key is the key, in bytes, to put into the key-value store. */
    bytes    key=1;
/* value is the value, in bytes, to associate with the key in the key-value store. */
    bytes    value=2;
/* lease is the lease ID to associate with the key in the key-value store. A lease value of 0 indicates no lease. */
    int64    lease=3;
/* If prev_kv is set, etcd gets the previous key-value pair before changing it. The previous key-value pair will be returned in the put response. */
bool    prev_kv=4;
/* If ignore_value is set, etcd updates the key using its current value. Returns an error if the key does not exist. */
    bool    ignore_value=5;
/* If ignore_lease is set, etcd updates the key using its current lease. Returns an error if the key does not exist. */
    bool    ignore_lease=6;
}

Key --- 放入key-value存储区的key的名称。

Value --- 与key-value存储中的key关联的值（以字节为单位）。

Lease ---与key-value存储中的key关联的Lease ID。Lease值为0表示没有Lease。

Prev_Kv --- 设置时，在从此Put请求更新之前使用key-value对数据进行响应。

Ignore_Value --- 设置后，更新key而不更改其当前值。如果key不存在，则返回错误。

Ignore_Lease --- 设置后，更新key而不更改其当前Lease。如果key不存在，则返回错误。

2.5 Put Response

message PutResponse    {
    ResponseHeader    header=1;
  /* if prev_kv is set in the request, the previous key-value pair will be returned. */
KeyValue    prev_kv=2;
}

作者：去去1002
链接：https://www.jianshu.com/p/942982973d16