彻底搞懂 etcd 系列文章（十）：etcd 租约 Lease API
彻底搞懂 etcd 系列文章（十）：etcd 租约 Lease API
0 专辑概述
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 的列表。
6 小结
本文主要介绍 etcd 租约 API 中涉及到的 LeaseGrant、LeaseRevoke、LeaseKeepAlive、LeaseTimeToLive 等主要方法，Lease API 是客户端实践中会经常用到，熟悉和了解这部分很有帮助。
订阅最新文章，欢迎关注我的公众号
- 彻底搞懂 etcd 系列文章（七）：etcd gRPC 服务 API
- 彻底搞懂 etcd 系列文章（八）：etcd 事务 API
- 彻底搞懂 etcd 系列文章（九）：etcd compact 和 watch API
参考
etcd docs