完全搞懂 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

](blueskykong.com/2020/08/27/…) 9. 完全搞懂 etcd 系列文章（八）：etcd 事务 API 10. 完全搞懂 etcd 系列文章（九）：etcd compact 和 watch API

参考

etcd docs