KV API guarantees

etcd是具有mini-transaction支持的一致且持久的key value存储。 etcd is a consistent and durable key value store with mini-transaction support. 这个key value存储通过KV APIs来暴露的。etcd试图为分布式系统提供了最强的一致性和持久性保证。 The key value store is exposed through the KV APIs. etcd tries to ensure the strongest consistency and durability guarantees for a distributed system. 本规范列举了etcd所做的KV API保证。 This specification enumerates the KV API guarantees made by etcd.

APIs to consider

• Read APIs
  • range
  • watch
• Write APIs
  • put
  • delete
• Combination (read-modify-write) APIs
  • txn
• Lease APIs
  • grant
  • revoke
  • put (attaching a lease to a key)

etcd specific definitions etcd 具体的定义

Operation completed 操作完成

当通过consensus提交后，etcd的操作被认为完成了， 如此“executed” – 永久的存储 – 通过etcd存储引擎。 客户端认为当从etcd server接收响应时那操作就完成了。 An etcd operation is considered complete when it is committed through consensus, and therefore “executed” – permanently stored – by the etcd storage engine. The client knows an operation is completed when it receives a response from the etcd server. 注意如果超时或者在客户端和etcd成员之间有网络中断，也许客户端不确定一个操作的状态。 Note that the client may be uncertain about the status of an operation if it times out, or there is a network disruption between the client and the etcd member. 当有领导选举时，etcd可能也会终止operations。在此事件中，etcd不会在有未完成的请求时向客户端发送abort响应。 etcd may also abort operations when there is a leader election. etcd does not send abort responses to clients’ outstanding requests in this event.

Revision

这是etcd的一个操作，当修改了key value存储时，这个操作会分配一个单独的自增revision。 An etcd operation that modifies the key value store is assigned a single increasing revision. 一个事物操作也许会修改key-value好多次，但是只有一个revision被指定。 A transaction operation might modify the key value store multiple times, but only one revision is assigned. 看不懂这一句 The revision attribute of a key value pair that was modified by the operation has the same value as the revision of the operation.

这个修订版本可以用作键值存储的逻辑时钟。 The revision can be used as a logical clock for key value store.

一个较小revision的键值对被修改之后有一个更大的revision。 A key value pair that has a larger revision is modified after a key value pair with a smaller revision.

具有相同的revision的两个键值对由一个操作“并发地”修改。 Two key value pairs that have the same revision are modified by an operation “concurrently”.

Guarantees provided 提供的保证

Atomicity 原子性

所有的API要求是原子的； 一个操作要么完成，要么不完成。 All API requests are atomic; an operation either completes entirely or not at all. 对于watch请求，一个操作生成的所有的事件将在一个watch中响应。Watch不会监控一个操作的部分事件。 For watch requests, all events generated by one operation will be in one watch response. Watch never observes partial events for a single operation.

Durability 持久化

任何完成的操作都是持久的。所有的访问数据也是持久数据。读取从来不会返回没有持久化的数据。 Any completed operations are durable. All accessible data is also durable data. A read will never return data that has not been made durable.

Isolation level and consistency of replicas 副本的隔离级别和一致性

etcd确定strict serializability 是分布式事物里的最强的隔离保障 etcd ensures strict serializability, which is the strongest isolation guarantee of distributed transactional database systems. 读操作不会观察到任何中间数据。（隔离等级可以参考） Read operations will never observe any intermediate data.

etcd确保linearizability 基于副本的一致性。 etcd ensures linearizability as consistency of replicas basically. 如下所述，异常是显示指定可系列化选项的监视操作和读取操作。 As described below, exceptions are watch operations and read operations which explicitly specifies serializable option.

从客户的角度出发，线性化提供了让推理容易的有用属性。这是一个清晰的描述，引用来自the original paper：Linearizability provides the illusion that each operation applied by concurrent processes takes effect instantaneously at some point between its invocation and its response.

From the perspective of client, linearizability provides useful properties which make reasoning easily. This is a clean description quoted from the original paper: Linearizability provides the illusion that each operation applied by concurrent processes takes effect instantaneously at some point between its invocation and its response.

例如，考虑客户端在时间点1（t1）完成写。client在t2 (for t2 > t1)时发出一个read，应该接收至少 For example, consider a client completing a write at time point 1 (t1). 客户端在t2 (t2 > t1)发出读操作时，接收到的值至少与上次写操作的值相同，且在t1时完成。

A client issuing a read at t2 (for t2 > t1) should receive a value at least as recent as the previous write, completed at t1.

但是，read可能只在t3时完成。线性化保证读返回最近的值。没有线性化保证，这个返回值 However, the read might actually complete only by t3. Linearizability guarantees the read returns the most current value.

没有线性的保证，当在t2时开始read，这个返回值也许在t3被“stale”，因为一个并发的write也许发生在t2 and t3. Without linearizability guarantee, the returned value, current at t2 when the read began, might be “stale” by t3 because a concurrent write might happen between t2 and t3.

etcd不能确定线性的watch操作。用户需验证watch返回的revision去确保正确的顺序。 etcd does not ensure linearizability for watch operations. Users are expected to verify the revision of watch responses to ensure correct ordering.

默认情况下，Etcd确保所有其他操作的线性化。 etcd ensures linearizability for all other operations by default. 然而，线性化是有代价的，因为线性化的请求必须经过Raft共识过程。 Linearizability comes with a cost, however, because linearized requests must go through the Raft consensus process. 为了得到更低的延迟和更高的读请求吞吐量，客户端可以将请求的的一致性模型配置为serializable， 可以访问稳定的数据 To obtain lower latencies and higher throughput for read requests, clients can configure a request’s consistency mode to serializable, which may access stale data with respect to quorum, but removes the performance penalty of linearized accesses' reliance on live consensus.

Granting, attaching and revoking leases 授予，附加和撤销leases

etcd提供了a lease mechanism. 这个lease的用例是实现分布式协作机制例如分布式锁。

etcd provides a lease mechanism. The primary use case of a lease is implementing distributed coordination mechanisms like distributed locks. 这个lease机制是简单的： 可以通过grantAPI创建一个lease，使用put API来设置key，使用revoke API来撤销，通过时钟存活时间（TTL）让key过期。 The lease mechanism itself is simple: a lease can be created with the grant API, attached to a key with the put API, revoked with the revoke API, and will be expired by the wall clock time to live (TTL). 但是，需要关心关于the important properties of the APIs and usage来实现正确的分布式协作机制。 However, users need to be aware about the important properties of the APIs and usage for implementing correct distributed coordination mechanisms.