彻底搞懂 etcd 系列文章（十）：etcd 租约 Lease API

etcd 是云原生架构中重要的基础组件，由 CNCF 孵化托管。etcd 在微服务和 Kubernates 集群中不仅可以作为服务注册与发现，还可以作为 key-value 存储的中间件。

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

1 etcd 租约服务

Lease service 提供租约的支持。Lease 是一种检测客户端存活状况的机制。群集授予具有生存时间的租约。如果 etcd 群集在给定的 TTL 时间内未收到 keepAlive，则租约到期。

为了将租约绑定到键值存储中，每个 key 最多可以附加一个租约。当租约到期或被撤销时，该租约所附的所有 key 都将被删除。每个过期的密钥都会在事件历史记录中生成一个删除事件。

在 rpc.proto 中 Lease service 定义的接口如下：

service Lease {

  rpc LeaseGrant(LeaseGrantRequest) returns (LeaseGrantResponse) {}

  rpc LeaseRevoke(LeaseRevokeRequest) returns (LeaseRevokeResponse) {}

  rpc LeaseKeepAlive(stream LeaseKeepAliveRequest) returns (stream LeaseKeepAliveResponse) {}

  rpc LeaseTimeToLive(LeaseTimeToLiveRequest) returns (LeaseTimeToLiveResponse) {}
}

• LeaseGrant 创建一个租约
• LeaseRevoke 撤销一个租约
• LeaseKeepAlive 用于维持租约
• LeaseTimeToLive 获取租约信息

下面分别介绍这几个方法。

2 LeaseGrant 方法

LeaseGrant 方法创建一个租约。当服务器在给定 time to live 时间内没有接收到 keepAlive 时租约过期。如果租约过期则所有附加在租约上的 key 将过期并被删除。每个过期的 key 在事件历史中生成一个删除事件。方法定义如下：

rpc LeaseGrant(LeaseGrantRequest) returns (LeaseGrantResponse) {}

请求的消息体是 LeaseGrantRequest：

message LeaseGrantRequest {
  int64 TTL = 1;

  int64 ID = 2;
}

TTL 建议以秒为单位的 time-to-live。ID 是租约的请求 ID，如果 ID 设置为 0，则出租人(也就是 etcd server)选择一个 ID。应答的消息体 LeaseGrantResponse 定义如下：

message LeaseGrantResponse {
  ResponseHeader header = 1;

  int64 ID = 2;

  int64 TTL = 3;
  string error = 4;
}

ID 是承认的租约的 ID。TTL 是服务器选择的以秒为单位的租约 time-to-live。

3 LeaseRevoke 方法

LeaseRevoke 撤销一个租约，此时所有附加到租约的 key 将过期并被删除。

rpc LeaseRevoke(LeaseRevokeRequest) returns (LeaseRevokeResponse) {}

请求的消息体 LeaseRevokeRequest 定义如下：

message LeaseRevokeRequest {

  int64 ID = 1;
}

ID 是要取消的租约的 ID。当租约被取消时，所有关联的 key 将被删除。应答的消息体 LeaseRevokeResponse 定义如下：

message LeaseRevokeResponse {
  ResponseHeader header = 1;
}

LeaseRevokeResponse 中只有一个通用的响应头字段。

4 LeaseKeepAlive 方法

LeaseKeepAlive 方法维持一个租约。LeaseKeepAlive 通过从客户端到服务器端的流化的 keep alive 请求和从服务器端到客户端的流化的 keep alive 应答来维持租约。

rpc LeaseKeepAlive(stream LeaseKeepAliveRequest) returns (stream LeaseKeepAliveResponse) {}

请求的消息体 LeaseKeepAliveRequest 定义如下：

message LeaseKeepAliveRequest {
  int64 ID = 1;
}

ID 是要继续存活的租约的 ID。应答的消息体 LeaseKeepAliveResponse：

message LeaseKeepAliveResponse {
  ResponseHeader header = 1;
  int64 ID = 2;

  int64 TTL = 3;
}

ID 是从继续存活请求中得来的租约 ID。TTL 是租约新的 time-to-live。

5 LeaseTimeToLive 方法

LeaseTimeToLive 方法获取租约的信息。

rpc LeaseTimeToLive(LeaseTimeToLiveRequest) returns (LeaseTimeToLiveResponse) {}

请求的消息体 LeaseTimeToLiveRequest 定义如下：

message LeaseTimeToLiveRequest {
  // ID 是租约的 ID
  int64 ID = 1;
  bool keys = 2;
}

keys 设置为 true 可以查询附加到这个租约上的所有 key。应答的消息体 LeaseTimeToLiveResponse 定义如下：

message LeaseTimeToLiveResponse {
  ResponseHeader header = 1;
  // ID 是来自请求的 ID
  int64 ID = 2;
  int64 TTL = 3;
  int64 grantedTTL = 4;
  repeated bytes keys = 5;
}

其中，TTL 是租约剩余的 TTL，单位为秒；租约将在接下来的 TTL + 1 秒之后过期。GrantedTTL 是租约创建/续约时初始授予的时间，单位为秒。keys 是附加到这个租约的 key 的列表。