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