彻底搞懂 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 是客户端实践中会经常用到，熟悉和了解这部分很有帮助。

订阅最新文章，欢迎关注我的公众号

推荐阅读

1. etcd 与 Zookeeper、Consul 等其它 k-v 组件的对比
2. 彻底搞懂 etcd 系列文章（一）：初识 etcd
3. 彻底搞懂 etcd 系列文章（二）：etcd 的多种安装姿势
4. 彻底搞懂 etcd 系列文章（三）：etcd 集群运维部署
5. 彻底搞懂 etcd 系列文章（四）：etcd 安全
6. 彻底搞懂 etcd 系列文章（五）：etcdctl 的使用
7. 彻底搞懂 etcd 系列文章（六）：etcd 核心 API v3
8. 彻底搞懂 etcd 系列文章（七）：etcd gRPC 服务 API
9. 彻底搞懂 etcd 系列文章（八）：etcd 事务 API
10. 彻底搞懂 etcd 系列文章（九）：etcd compact 和 watch API

参考

etcd docs