通用探索 API 元件 (proto)

service.discovery.v3.ResourceLocator

[service.discovery.v3.ResourceLocator proto]

指定要訂閱的資源。

{
  "name": ...,
  "dynamic_parameters": {...}
}

name: (string) 要訂閱的資源名稱。

dynamic_parameters: (repeated map<string, string>) 一組動態參數，用於比對資源上的動態參數限制。這允許用戶端在同一資源的多個變體之間進行選擇。

service.discovery.v3.ResourceName

[service.discovery.v3.ResourceName proto]

指定具體的資源名稱。

{
  "name": ...,
  "dynamic_parameter_constraints": {...}
}

name: (string) 資源的名稱。

dynamic_parameter_constraints: (service.discovery.v3.DynamicParameterConstraints) 與此資源關聯的動態參數限制。由用戶端快取（包括 xDS 代理）在比對訂閱的資源定位器時使用。

service.discovery.v3.DiscoveryRequest

[service.discovery.v3.DiscoveryRequest proto]

DiscoveryRequest 為指定 Envoy 節點在某些 API 上請求一組相同類型的版本化資源。

{
  "version_info": ...,
  "node": {...},
  "resource_names": [],
  "type_url": ...,
  "response_nonce": ...,
  "error_detail": {...}
}

version_info: (string) 請求訊息中提供的 version_info 將是最近成功處理的回應中收到的 version_info，或在第一次請求時為空。預期在收到回應後，不會傳送新的請求，直到 Envoy 實例準備好 ACK/NACK 新設定。ACK/NACK 通過返回應用時的新 API 設定版本或先前的 API 設定版本來進行。每個 type_url（請參閱下文）都有一個與其關聯的獨立版本。

node: (config.core.v3.Node) 發出請求的節點。

resource_names: (repeated string) 要訂閱的資源列表，例如叢集名稱列表或路由設定名稱。如果此項為空，則會傳回 API 的所有資源。LDS/CDS 可能有空的 resource_names，這將導致傳回 Envoy 實例的所有資源。然後，LDS 和 CDS 回應將暗示需要通過 EDS/RDS 擷取的資源數量，這些資源將在 resource_names 中明確列舉。

type_url: (string) 所請求資源的類型，例如 “type.googleapis.com/envoy.api.v2.ClusterLoadAssignment”。這在通過單例 xDS API（例如 CDS、LDS 等）發出的請求中是隱含的，但對於 ADS 是必需的。

response_nonce: (string) 對應於被 ACK/NACK 的 DiscoveryResponse 的 nonce。請參閱上面關於 version_info 和 DiscoveryResponse nonce 註解的討論。僅當 1) 這是非持久串流 xDS（例如 HTTP）或 2) 用戶端尚未接受此 xDS 串流中的更新時，此項才可能為空（與 delta 不同，delta 僅針對新的顯式 ACK 填充）。

error_detail: (Status) 當先前的 DiscoveryResponse 未能更新設定時，將會填充此欄位。error_details 中的 message 欄位提供了與失敗相關的 Envoy 內部例外狀況。它僅供手動除錯時使用，所提供的字串不保證在不同的 Envoy 版本中保持穩定。

service.discovery.v3.DiscoveryResponse

[service.discovery.v3.DiscoveryResponse proto]

{
  "version_info": ...,
  "resources": [],
  "type_url": ...,
  "nonce": ...,
  "control_plane": {...}
}

version_info: (string) 回應資料的版本。

resources: (repeated Any) 回應資源。這些資源是類型化的，並且取決於正在呼叫的 API。

type_url: (string) 資源的類型 URL。在 ADS 上進行多路複用時識別 xDS API。必須與 ‘resources’ 重複 Any 中的 type_url 一致（如果非空）。

nonce: (string) 對於基於 gRPC 的訂閱，nonce 提供了一種在後續 DiscoveryRequest 中顯式確認特定 DiscoveryResponse 的方法。在傳送回應時，Envoy 可能已向管理伺服器傳送了先前版本串流的其他訊息，這些訊息在回應傳送時未處理。Nonce 允許管理伺服器忽略任何先前版本的其他 DiscoveryRequest，直到收到帶有 nonce 的 DiscoveryRequest。Nonce 是可選的，對於非基於串流的 xDS 實作不是必需的。

control_plane: (config.core.v3.ControlPlane) 發送回應的控制平面實例。

service.discovery.v3.DeltaDiscoveryRequest

[service.discovery.v3.DeltaDiscoveryRequest proto]

DeltaDiscoveryRequest 和 DeltaDiscoveryResponse 用於 Delta xDS 的新 gRPC 端點。

使用 Delta xDS 時，DeltaDiscoveryResponse 不需要包含追蹤資源的完整快照。相反，DeltaDiscoveryResponse 是 xDS 用戶端狀態的差異。在 Delta XDS 中，有每個資源的版本，這允許在資源粒度上追蹤狀態。xDS Delta 會話始終在 gRPC 雙向串流的上下文中。這允許 xDS 伺服器追蹤連接到它的 xDS 用戶端的狀態。

在 Delta xDS 中，nonce 欄位是必需的，用於將 DeltaDiscoveryResponse 與 DeltaDiscoveryRequest ACK 或 NACK 配對。選擇性地，回應訊息層級的 system_version_info 僅用於除錯目的。

DeltaDiscoveryRequest 扮演兩個獨立的角色。任何 DeltaDiscoveryRequest 都可以是以下其中之一或兩者：[1] 通知伺服器用戶端對哪些資源產生/失去興趣（使用 resource_names_subscribe 和 resource_names_unsubscribe），或 [2] (N)ACK 先前來自伺服器的資源更新（使用 response_nonce，存在 error_detail 使其成為 NACK）。此外，重新連線的 gRPC 串流的第一個訊息（對於給定的 type_url）還有第三個角色：使用 initial_resource_versions 欄位通知伺服器用戶端已擁有的資源（及其版本）。

與世界狀態一樣，當多個資源類型進行多路複用 (ADS) 時，所有請求/確認/更新都會通過 type_url 在邏輯上隔開：叢集 ACK 與先前的路由 NACK 存在於完全不同的世界中。特別是，在每個 gRPC 串流「開始」時傳送的 initial_resource_versions 實際上需要每個 type_url 的訊息，每個訊息都有自己的 initial_resource_versions。

{
  "node": {...},
  "type_url": ...,
  "resource_names_subscribe": [],
  "resource_names_unsubscribe": [],
  "initial_resource_versions": {...},
  "response_nonce": ...,
  "error_detail": {...}
}

node: (config.core.v3.Node) 發出請求的節點。

type_url: (string) 所請求資源的類型，例如 type.googleapis.com/envoy.api.v2.ClusterLoadAssignment。如果僅通過 xds_resource_subscribe 和 xds_resources_unsubscribe 引用資源，則無需設定此項。

resource_names_unsubscribe: (repeated string) 要從追蹤資源列表中移除的資源名稱列表。

initial_resource_versions: (repeated map<string, string>) 通知伺服器 xDS 客戶端已知的資源版本，以便即使在 gRPC 串流重新連線的情況下，客戶端也能繼續相同的邏輯 xDS 會話。在以下情況下，此欄位將不會被填入：[1] 在會話的第一個串流中，因為客戶端尚未擁有任何資源；[2] 在串流中的第一個訊息之後的任何訊息（對於給定的 type_url），因為伺服器已經正確追蹤客戶端的狀態。（在 ADS 中，重新連線的串流的每個 type_url的第一個訊息會填入此 map。）此 map 的鍵是 xDS 客戶端已知的 xDS 資源名稱。此 map 的值是不透明的資源版本。

response_nonce: (string) 當 DeltaDiscoveryRequest 是針對先前的 DeltaDiscoveryResponse 的 ACK 或 NACK 訊息時，response_nonce 必須是 DeltaDiscoveryResponse 中的 nonce。否則（與 DiscoveryRequest 不同），必須省略 response_nonce。

error_detail: (Status) 當先前的 DiscoveryResponse 無法更新設定時，此欄位會被填入。error_details 中的 message 欄位會提供與失敗相關的 Envoy 內部例外狀況。

service.discovery.v3.DeltaDiscoveryResponse

[service.discovery.v3.DeltaDiscoveryResponse proto]

{
  "system_version_info": ...,
  "resources": [],
  "type_url": ...,
  "removed_resources": [],
  "removed_resource_names": [],
  "nonce": ...
}

system_version_info: (string) 回應資料的版本（用於偵錯）。

resources: (repeated service.discovery.v3.Resource) 回應資源。這些是類型化的資源，其類型必須與 type_url 欄位相符。

type_url: (string) 資源的 Type URL。在透過 ADS 進行多工處理時，識別 xDS API。如果 ‘resources’ 非空，則必須與 ‘resources’ 中 Any 內的 type_url 一致。

removed_resources: (repeated string) 已刪除且要從 xDS 客戶端移除的資源名稱。遺失資源的已移除資源可以忽略。

removed_resource_names: (repeated service.discovery.v3.ResourceName) removed_resources 的替代方案，允許指定正在移除的資源變體。對於任何將動態參數約束發送到客戶端的資源，都必須使用此變體。

nonce: (string) nonce 提供了一種在 (N)ACK 時，讓 DeltaDiscoveryRequests 唯一參考 DeltaDiscoveryResponse 的方法。nonce 是必需的。

service.discovery.v3.DynamicParameterConstraints

[service.discovery.v3.DynamicParameterConstraints proto]

一組與個別 xDS 資源變體相關聯的動態參數約束。這些約束會根據訂閱中的動態參數集，判斷資源是否符合訂閱，如 ResourceLocator.dynamic_parameters 欄位中所指定。這允許 xDS 實作（客戶端、伺服器和快取代理）判斷哪個資源變體適合給定的客戶端。

{
  "constraint": {...},
  "or_constraints": {...},
  "and_constraints": {...},
  "not_constraints": {...}
}

constraint

(service.discovery.v3.DynamicParameterConstraints.SingleConstraint) 要評估的單一約束。

只能設定 constraint、or_constraints、and_constraints、not_constraints 中的一個。

or_constraints

(service.discovery.v3.DynamicParameterConstraints.ConstraintList) 如果列表中的任何一個約束符合，則符合的約束列表。

只能設定 constraint、or_constraints、and_constraints、not_constraints 中的一個。

and_constraints

(service.discovery.v3.DynamicParameterConstraints.ConstraintList) 必須全部符合的約束列表。

只能設定 constraint、or_constraints、and_constraints、not_constraints 中的一個。

not_constraints

(service.discovery.v3.DynamicParameterConstraints) 一組約束的反向（NOT）。

只能設定 constraint、or_constraints、and_constraints、not_constraints 中的一個。

service.discovery.v3.DynamicParameterConstraints.SingleConstraint

[service.discovery.v3.DynamicParameterConstraints.SingleConstraint proto]

給定鍵的單一約束。

{
  "key": ...,
  "value": ...,
  "exists": {...}
}

key: (string) 要比對的鍵。

value

(string) 比對此確切值。

必須設定 value 和 exists 中的其中一個。

exists

(service.discovery.v3.DynamicParameterConstraints.SingleConstraint.Exists) 鍵存在（比對除了鍵不存在之外的任何值）。這允許為根本不發送鍵的客戶端設定預設約束，同時可能會有其他需要根據該鍵進行特殊設定的客戶端。

必須設定 value 和 exists 中的其中一個。

service.discovery.v3.DynamicParameterConstraints.SingleConstraint.Exists

[service.discovery.v3.DynamicParameterConstraints.SingleConstraint.Exists proto]

service.discovery.v3.DynamicParameterConstraints.ConstraintList

[service.discovery.v3.DynamicParameterConstraints.ConstraintList proto]

{
  "constraints": []
}

constraints: (repeated service.discovery.v3.DynamicParameterConstraints)

service.discovery.v3.Resource

[service.discovery.v3.Resource proto]

{
  "name": ...,
  "resource_name": {...},
  "aliases": [],
  "version": ...,
  "resource": {...},
  "ttl": {...},
  "metadata": {...}
}

name: (string) 資源的名稱，以區分相同類型的其他資源。只能設定 name 或 resource_name 中的一個。

resource_name: (service.discovery.v3.ResourceName) name 欄位的替代方案，當伺服器支援以動態參數約束區分的命名資源的多個變體時使用。只能設定 name 或 resource_name 中的一個。

aliases: (repeated string) 別名是此資源可以使用的其他名稱的列表。

version: (string) 資源層級版本。它允許 xDS 追蹤個別資源的狀態。

resource: (Any) 正在追蹤的資源。

ttl

(Duration) 資源的存留時間值。對於每個資源，都會啟動一個計時器。每次收到具有新 TTL 的資源時，都會重設計時器。如果收到的資源沒有設定 TTL，則會移除該資源的計時器。計時器過期時，將會移除該資源的設定。

可以透過發送不變更資源版本的回應來重新整理或變更 TTL。在這種情況下，資源欄位不需要填入，這允許輕量級的「心跳」更新，以保持具有 TTL 的資源處於活動狀態。

TTL 功能旨在支援在管理伺服器發生故障時應移除的設定。例如，此功能可用於故障注入測試，其中在 Envoy 與管理伺服器失去連線的情況下，應終止故障注入。

metadata: (config.core.v3.Metadata) Metadata 欄位可用於提供資源的其他資訊。例如，用於偵錯的追蹤資料。