0 Album Overview

Etcd is an important foundation component in the cloud native architecture and is incubated and hosted by CNCF. Etcd can be used not only as service registration and discovery, but also as middleware for key-value storage in microservices and Kubernates clusters.

“Thoroughly Understand ETCD series of articles” will be from the basic function of ETCD practice, API interface, implementation principle, source code analysis, as well as the implementation of the pit experience and other aspects of the specific introduction of ETCD. It is expected that there will be about 20 articles, I will continue to update every week, welcome to pay attention to.

1 Overview of Etcd API

This article will begin by introducing the core design of the ETCD3 API, focusing on common API interface services. It is very helpful to understand the basic idea of ETCD. All ETCD3 apis are defined in the gRPC service, which classifies remote procedure calls (RPCS) that are understood by the ETCD server.

2 gRPC service

Each API request sent to the ETCD server is a gRPC remote procedure call. The RPC interface definitions in ETCD3 are classified into services based on functionality.

Important services for handling ETCD key values include:

  • KV service, create, update, get and delete key-value pairs.
  • Monitor, monitor key changes.
  • Lease, which consumes primitives for the client to keep active messages.
  • Lock, etCD provides support for distributed shared locks.
  • Election, exposing the client-side election mechanism.

2.1 Request and Response

All RPCS in ETCD3 follow the same format. Each RPC has a function name that takes NameRequest as an argument and returns NameResponse as a response. For example, here is the Range RPC description:

service KV {
  Range(RangeRequest) returns (RangeResponse)
  ...
}
Copy the code

2.2 response headers

All responses to the ETCD API have an additional response header that includes the cluster metadata for the response:

message ResponseHeader {
  uint64 cluster_id = 1;
  uint64 member_id = 2;
  int64 revision = 3;
  uint64 raft_term = 4;
}
Copy the code
  • Cluster_ID – ID of the cluster that generates the response.
  • Member_ID – ID of the member that generated the response.
  • Revision – The Revision number of the key value store when the response was generated.
  • Raft_Term – Raft title for the member when the response is generated.

The application service can use the Cluster_ID and Member_ID fields to ensure that it is currently communicating with the expected cluster or member.

The application service can use the revision number field to know the latest revision number of the current key-value repository. This feature is particularly useful when an application specifies a historical revision to make a time history query and wants to know the latest revision when requested.

Application services can use Raft_Term to detect when a cluster has completed a new leader election.

3 Key/value pair service

3.1 Definition of KV Service

Most requests to ETCD are usually key-value requests. KV Service provides support for key-value pair operations. In the rpc.proto file, KV service is defined as follows:

//rpc.proto service KV { rpc Range(RangeRequest) returns (RangeResponse) {} rpc Put(PutRequest) returns (PutResponse) {}  rpc DeleteRange(DeleteRangeRequest) returns (DeleteRangeResponse) {} rpc Txn(TxnRequest) returns (TxnResponse) {} rpc Compact(CompactionRequest) returns (CompactionResponse) {} }Copy the code

Each function is described as follows:

  • Range, which retrieves a Range of keys from the key-value store.
  • Put, sets the given key to the key-value store. Put requests to increment the revised version of the key-value store and generates an event in the event history.
  • DeleteRange, deletes a given range from the key-value store, requests to add a revised version of the key-value store and generates a delete event in the event history for each deleted key;
  • Txn, which processes multiple requests in a single transaction. A Txn request increments a revised version of the key-value store and generates an event with the same revised version for each completed request. Do not allow multiple key changes in a TXN;
  • Compact, compacts the event history in the ETCD key-value store. The key-value store should be compressed periodically, otherwise the event history will continue to grow indefinitely.

Let’s look at each interface method in detail.

3.2 Range method

The Range method retrieves a Range of keys from the key-value store, defined as follows:

rpc Range(RangeRequest) returns (RangeResponse) {}

Copy the code

Note that there is no way to manipulate a single key, and even to access a single key, you need to use the Range method. The requested message body, RangeRequest, looks like this:

message RangeRequest { enum SortOrder { NONE = 0; // By default, ASCEND = 1; // DESCEND, low value in front of hajj = 2; } enum SortTarget {KEY = 0; VERSION = 1; CREATE = 2; MOD = 3; VALUE = 4; } bytes key = 1; // range_end is the upper limit of the request range [key, Range_end) bytes range_end = 2; // limit on the number of returned keys int64 limit = 3; int64 revision = 4; // specify the SortOrder of returned results SortOrder Sort_order = 5; // SortTarget sort_target = 6; bool serialIZABLE = 7; // Only return key without value bool keYS_only = 8; Bool count_only = 9;}Copy the code

In the request structure definition above, note that key is the first key in the range. If range_end is not given, the request looks for this key only. Range_end represents the upper limit of the request. If range_end is ‘\0’, the range is all keys greater than or equal to key; If range_end is one bit longer than the given key, range asks for all keys prefixed with the given key; If both key and range_end are ‘\0’, the range query returns all keys. Revision Revision was made at the point in time when the range key and value pairs were stored. If revision is less than or equal to zero, the range is on the most recent key-value pair store. If the revision has been compressed, return ErrCompacted as a response. Serializable set range requests use serialized members to read locally. Range requests are linearized by default. Linearized requests have higher latency and lower throughput than serialized requests, but reflect the current consistency of the cluster. For better performance, at the expense of potentially dirty reads, serialized range requests are processed locally and do not need to be consistent with other nodes in the cluster.

The response body RangeResponse is defined as follows:

message RangeResponse { ResponseHeader header = 1; // KVS is a list of key/value pairs matching range requests. // An empty repeated mvccpb.KeyValue KVS = 2; Bool more = 3; // More indicates whether there are more keys in the range requested. Int64 count = 4; }Copy the code

The header is the generic response header mentioned in the previous section. The message body of mvccpb.KeyValue is defined as follows:

Message KeyValue {// key is a key in bytes format. Bytes key = 1; // create_revision is the last revision created by this key int64 create_revision = 2; // mod_revision is the last revision of this key int64 mod_revision = 3; int64 version = 4; // Value is the value held by the key. Bytes is used. bytes value = 5; int64 lease = 6; }Copy the code

Version is the version of the key. Deletion resets the version to 0, and any changes to the key increase its version. Lease is the LEASE ID attached to the key. When the additional lease expires, the key is deleted. If lease is 0, no lease is attached to the key.

3.3 Put method

The Put method is used to store the given key to the database. The Put method increments the revised version of the key-value store and generates an event in the event history.

rpc Put(PutRequest) returns (PutResponse) {}
Copy the code

The request message body is PutRequest:

Message PutRequest {// byte An array of keys to place in the key-value pair store bytes key = 1; Bytes value = 2 in key-value pair storage. int64 lease = 3; bool prev_kv = 4; }Copy the code

Lease: indicates the LEASE ID associated with the key in the key-value store. 0 indicates that there is no lease. If prev_KV is set, etCD gets the previous key-value pair before changing. The previous key-value pair will be returned in the PUT reply.

The response body PutResponse is defined as follows:

message PutResponse {
  ResponseHeader header = 1;

  mvccpb.KeyValue prev_kv = 2;
}
Copy the code

Header represents the generic response header. If prev_KV is set in the request, the previous key-value pair will be returned.

3.4 DeleteRange method

The DeleteRange method deletes the given range from the key-value store. The delete request adds a revised version of the key-value store and generates a delete event in the event history for each deleted key.

rpc DeleteRange(DeleteRangeRequest) returns (DeleteRangeResponse)
Copy the code

The requested message body DeleteRangeRequest is defined as follows:

message DeleteRangeRequest { 
  bytes key = 1;

  bytes range_end = 2;

  bool prev_kv = 3;
}
Copy the code

Key represents the beginning of the scope to delete. Range_end is the last key to remove the range [key, range_end]. If range_end is not given, the range is defined to contain only the key argument; if range_end is ‘\0’, If prev_kv is set, etcd retrieves the last key-value pair before deletion. The last key-value pair is returned in the delete reply. The body of the reply DeleteRangeResponse is defined as follows:

message DeleteRangeResponse { ResponseHeader header = 1; Int64 deleted = 2; // Number of deleted keys int64 deleted = 2; repeated mvccpb.KeyValue prev_kvs = 3; }Copy the code

If prev_KV is set in the request, the previous key-value pair is returned.

4 summary

This paper mainly introduces the CONTENT related to KV service and gRPC request response involved in Etcd API, understanding these is an important prerequisite for us to learn Etcd RPC call. The following articles will continue to cover these important services and interfaces in ETCD.

Subscribe to the latest articles, welcome to follow my official account

Recommended reading

  1. Comparison between ETCD and other K-V components such as Zookeeper and Consul
  2. Thoroughly understand ETCD series article (1) : first know ETCD
  3. Thoroughly understand etCD series article (2) : ETCD installation posture
  4. Thoroughly understand etCD series (3) : ETCD cluster operation and maintenance deployment
  5. Thoroughly understand etCD series article (four) : ETCD security
  6. Thoroughly understand the etCD series article (five) : the use of ETCDCTL
  7. Thoroughly understand etCD series article (6) : ETCD core API V3

reference

etcd docs