Etcd教程 — 第八章 Etcd之Compact、Watch和Lease API

一、Compact 壓縮

Compact方法是壓縮Etcd鍵值對存儲中的事件曆史。鍵值對存儲應該定期壓縮，否則事件曆史會無限制的持續增長。

rpc Compact(CompactionRequest) returns (CompactionResponse) {}

請求的消息體是 CompactionRequest， CompactionRequest 是壓縮鍵值對存儲到給定修訂版本。所有修訂版本比壓縮修訂版本小的鍵都將被删除：

message CompactionRequest {
  // 鍵值存儲的修訂版本，用於比較操作
  int64 revision = 1;

  bool physical = 2;
}

physical 設置為 true 時 RPC 將會等待直到壓縮物理性的應用到本地數據庫，到這程度被壓縮的項將完全從後端數據庫中移除。應答的消息體 CompactionResponse 定義為：

message CompactionResponse {
  ResponseHeader header = 1;
}

CompactionResponse 只有一個通用的響應頭。

二、Watch 服務

Watch API 提供了一個基於事件的接口，用於异步監視鍵的更改。Etcd3監視程序通過從給定的修訂版本（當前版本或曆史版本）持續監視 key 更改，並將 key 更新流回客戶端。

事件

每個鍵的更改都用事件消息錶示。 事件消息會同時提供更新數據和更新類型，mvccpb.Event 的消息體定義如下：

message Event {
  enum EventType {
    PUT = 0;
    DELETE = 1;
  }

  EventType type = 1;

  KeyValue kv = 2;

  // prev_kv 持有在事件發生前的鍵值對
  KeyValue prev_kv = 3;
}

type 是事件的類型。如果類型是 PUT，錶明新的數據已經存儲到 key；如果類型是 DELETE， 錶明 key 已經被删除。

kv 為事件持有 KeyValue。PUT 事件包含當前的 kv 鍵值對。kv.Version=1 的 PUT 事件錶明 key 的創建。DELETE/EXPIRE 事件包含被删除的 key，它的修改修訂版本設置為删除的修訂版本。

監視流

Watch API 提供了一個基於事件的接口，用於异步監視鍵的更改。etcd 監視程序通過從給定的修訂版本（當前版本或曆史版本）連續監視來等待密鑰更改，並將密鑰更新流回客戶端。

監視持續運行，並使用 gRPC 來流式傳輸事件數據。監視流是雙向的，客戶端寫入流以建立監視事件，並讀取以接收監視事件。單個監視流可以通過使用每個觀察器標識符標記事件來複用許多不同的觀察。這種多路複用有助於减少 etcd 群集上的內存占用量和連接開銷。

Watch 事件具有如下三個特性：

• 有序，事件按修訂順序排序；如果事件早於已發布的事件，它將永遠不會出現在列錶上。
• 可靠，事件序列永遠不會丟弃任何事件子序列；如果按時間順序為 a < b < c 三個事件，那麼如果 Watch 接收到事件 a 和 c，則可以保證接收到 b。
• 原子，保證事件清單包含完整的修訂版；同一修訂版中通過多個鍵進行的更新不會拆分為多個事件列錶。

Watch service 定義
在 rpc.proto 中 Watch service 定義如下：

service Watch {
  rpc Watch(stream WatchRequest) returns (stream WatchResponse) {}
}

Watch 觀察將要發生或者已經發生的事件。輸入和輸出都是流;輸入流用於創建和取消觀察，而輸出流發送事件。一個觀察 RPC 可以在一次性在多個 key 範圍上觀察，並為多個觀察流化事件。整個事件曆史可以從最後壓縮修訂版本開始觀察。

WatchService 只有一個 Watch 方法。

請求的消息體 WatchRequest 定義如下：

message WatchRequest {
  oneof request_union {
    WatchCreateRequest create_request = 1;
    WatchCancelRequest cancel_request = 2;
  }
}

request_union 要麼是創建新的觀察者的請求，要麼是取消一個已經存在的觀察者的請求。創建新的觀察者的請求 WatchCreateRequest：

message WatchCreateRequest {
  // key 是注册要觀察的 key
  bytes key = 1;

  bytes range_end = 2;

  // start_revision 是可選的開始(包括)觀察的修訂版本。不設置 start_revision 則錶示 "現在".
  int64 start_revision = 3;

  bool progress_notify = 4;

  enum FilterType {
  // 過濾掉 put 事件
  NOPUT = 0;

  // 過濾掉 delete 事件
  NODELETE = 1;
  }

  // 過濾器，在服務器端發送事件給回觀察者之前，過濾掉事件。
  repeated FilterType filters = 5;

  // 如果 prev_kv 被設置，被創建的觀察者在事件發生前獲取上一次的KV。
  // 如果上一次的KV已經被壓縮，則不會返回任何東西
  bool prev_kv = 6;
}

• range_end 是要觀察的範圍 [key, range_end) 的終點。如果 range_end 沒有設置，則只有參數 key 被觀察；如果 range_end 等同於 ‘\0’， 則大於等於參數 key 的所有 key 都將被觀察；如果 range_end 比給定 key 大1， 則所有以給定 key 為前綴的 key 都將被觀察。

• progress_notify 設置，這樣如果最近沒有事件，etcd 服務器將定期的發送不帶任何事件的 WatchResponse 給新的觀察者。當客戶端希望從最近已知的修訂版本開始恢複斷開的觀察者時有用。etcd 服務器將基於當前負載决定它發送通知的頻率。

取消已有觀察者的 WatchCancelRequest：

message WatchCancelRequest {
  int64 watch_id = 1;
}

watch_id 是要取消的觀察者的id，這樣就不再有更多事件傳播過來了。

應答的消息體 WatchResponse：

message WatchResponse {
  ResponseHeader header = 1;
  // watch_id 是和應答相關的觀察者的ID
  int64 watch_id = 2;

  bool created = 3;

  bool canceled = 4;

  int64 compact_revision  = 5;

  // cancel_reason 指出取消觀察者的理由.
  string cancel_reason = 6;

  repeated mvccpb.Event events = 11;
}

• 如果應答是用於創建觀察者請求的，則 created 設置為 true。客戶端應該記錄 watch_id 並期待從同樣的流中為創建的觀察者接收事件。所有發送給被創建的觀察者的事件將附帶同樣的 watch_id；如果應答是用於取消觀察者請求的，則 canceled 設置為true。不會再有事件發送給被取消的觀察者。
• compact_revision 被設置為最小 index，如果觀察者試圖觀察被壓縮的 index。當在被壓縮的修訂版本上創建觀察者或者觀察者無法追上鍵值對存儲的進展時發生。客戶端應該視觀察者為被取消，並不應該試圖再次創建任何帶有相同 start_revision 的觀察者。

三、Lease 服務

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：獲取租約信息

3.1 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.2 LeaseRevoke 方法

LeaseRevoke 撤銷一個租約，此時所有附加到租約的 key 將過期並被删除。

rpc LeaseRevoke(LeaseRevokeRequest) returns (LeaseRevokeResponse) {}

請求的消息體 LeaseRevokeRequest 定義如下：

message LeaseRevokeRequest {

  int64 ID = 1;
}

ID 是要取消的租約的 ID。當租約被取消時，所有關聯的 key 將被删除。

應答的消息體 LeaseRevokeResponse 定義如下：

message LeaseRevokeResponse {
  ResponseHeader header = 1;
}

LeaseRevokeResponse 中只有一個通用的響應頭字段。

3.3 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。

3.4 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 的列錶。