摘要簡介

Service Extensions 可讓您從網路 Proxy 發出呼叫。 大多數應用程式負載平衡器都支援標註擴充功能。Secure Web Proxy (預先發布版) 也支援註解擴充功能。

註解資料流程

網路 Proxy 會使用下列其中一種 Envoy gRPC 協定，與呼叫進行通訊：

  • 外部處理或 ext_proc 通訊協定。

    這項通訊協定支援路徑、流量和授權擴充功能，且為預設通訊協定。

    擴充功能服務可透過 ext_proc 通訊協定檢查及修改要求標頭或主體，回應 HTTP 要求生命週期中的事件。

  • 外部授權或 ext_authz 通訊協定。

    這個通訊協定僅支援授權擴充功能。ext_authz 支援服務目前為預先發布版。

    ext_authz 通訊協定會將授權決策委派給外部獨立服務，以處理傳入要求。這個 API 可讓擴充功能服務檢查要求的標頭或中繼資料，回應 HTTP 要求生命週期中的事件，做出複雜的授權決策。

    設定授權擴充功能時，可以使用 wireFormat 選項指定這個通訊協定。

您可以在虛擬機器 (VM) 執行個體或 GKE 上部署這些擴充服務，並設定執行個體群組或網路端點群組 (NEG)，代表這些服務的端點。

範例部署情境

下圖顯示部署情境範例。您可以在使用者管理的運算資源 (例如 VM 執行個體或 Google Kubernetes Engine (GKE) 叢集) 上，透過 gRPC 伺服器部署回呼後端服務，並以一般後端服務的形式向負載平衡器表示。

應用程式負載平衡器會使用呼叫，納入來自呼叫後端服務的自訂邏輯。
應用程式負載平衡器會傳送 Service Extensions 呼叫，藉此呼叫後端服務 (按一下可放大)。

摘要額外資訊與 ext_proc 的搭配運作方式

ext_proc gRPC API 的簡短版本如下。

// The gRPC API to be implemented by the external processing server
service ExternalProcessor {
  rpc Process(stream ProcessingRequest) returns (stream ProcessingResponse) {
  }
}

// Envoy sets one of these fields depending on the processing stage.
message ProcessingRequest {
  oneof request {
    HttpHeaders request_headers = 2;
    HttpHeaders response_headers = 3;
    HttpBody request_body = 4;
    HttpBody response_body = 5;
  }
}

message ProcessingResponse {
  oneof response {
    HeadersResponse request_headers = 1;
    HeadersResponse response_headers = 2;
    BodyResponse request_body = 3;
    BodyResponse response_body = 4;

    ImmediateResponse immediate_response = 7;
  }
}

收到 HTTP 要求標頭後，應用程式負載平衡器和 Secure Web Proxy 會將 ProcessingRequest 訊息傳送至擴充功能服務，並將 request_headers 欄位設為來自用戶端的 HTTP 標頭。

擴充功能服務必須以相應的 ProcessingResponse 訊息回應 ProcessingRequest 訊息，其中包含對 ProcessingRequest 訊息標頭或內文所做的任何設定變更。或者，服務可以設定 immediate_response 欄位，讓網路 Proxy 結束要求處理作業，並將指定的回應傳回給用戶端。

對於 REQUEST_HEADER 和 RESPONSE_HEADER 事件，擴充功能服務可以操控要求或回應中的 HTTP 標頭。服務可以透過在 ProcessingResponse 訊息中適當設定 request_headers 或 response_headers 欄位，新增、修改或刪除標頭。使用 raw_value 欄位做為標頭。

流量擴充功能可變更要求和回應的標頭和內文。擴充功能伺服器可以動態覆寫處理模式，並允許在後續階段啟用或停用擴充功能。呼叫流量擴充功能後，負載平衡器不會重新評估路徑規則。

邊緣、授權和路徑擴充功能僅支援 HTTP 標頭。這些擴充功能無法檢查或變更 HTTP 內文。

如果是路徑和流量擴充功能，當擴充功能的 observabilityMode 設為 true，且主體處理模式為 STREAMED (預設) 時，標註可以非同步執行。系統會非同步呼叫擴充功能後端，不會暫停處理進行中的要求。系統會略過回應 (如有)。

摘要額外資訊與 ext_authz 的搭配運作方式

ext_authz API 僅支援授權摘要額外資訊。

API 的簡短版本如下。

// A generic interface for performing authorization checks on incoming
// requests to a networked service.
service Authorization {
  // Performs an authorization check based on the attributes associated with
  // the incoming request and return status.
  rpc Check(CheckRequest) returns (CheckResponse) {
  }
}

message CheckRequest {
  // The request attributes.
  AttributeContext attributes = 1;
}

message CheckResponse {
  google.rpc.Status status = 1;
  oneof http_response {
    DeniedHttpResponse denied_response = 2;
    OkHttpResponse ok_response = 3;
  }
  google.protobuf.Struct dynamic_metadata = 4;
}

收到 HTTP 要求標頭後，負載平衡器會將 CheckRequest 訊息傳送至擴充功能服務。

擴充功能服務必須以相應的 CheckResponse 訊息回覆 CheckRequest 訊息，其中包含下列資訊：

  • status：表示狀態。OK 表示要求已獲准。如果傳回其他狀態，則表示要求遭拒。

  • denied_response 或 ok_response：表示是否允許回應。這個欄位會隨附授權檢查的相關 HTTP 回應屬性。

    • 授權服務允許要求時，會使用 ok_response 欄位。這項服務可以修改、新增或移除任何原始要求標頭，並更新傳送至用戶端的 HTTP 回應標頭。使用 raw_value 欄位做為標頭。

    • 授權服務拒絕要求時，會使用 denied_response 欄位。服務可以更新傳送至用戶端的 HTTP 回應標頭。

    如果擴充功能服務透過 CheckResponse 訊息傳回不允許的標頭名稱或值，系統會拒絕要求並傳回 500 Internal Error 狀態碼。如要瞭解禁止使用的標頭，請參閱「標頭操縱的限制」一節。

  • dynamic_metadata：包含選用中繼資料，供授權擴充功能之後呼叫的任何擴充功能使用，例如流量擴充功能。

身體處理模式

對於支援內文處理的擴充功能，您可以分別設定 request_body_send_mode 或 response_body_send_mode 欄位的值，為要求和回應內文處理設定下列兩種傳送模式之一。

預設模式為 STREAMED，適用於多數用途。

模式 說明 必須提供支援的事件 支援的擴充功能
STREAMED

通話會在串流模式中執行。如果未設定模式，系統也會使用這項預設設定。

Proxy 會將主體區塊傳送至擴充功能服務，並預期每個區塊都會收到單一回應。擴充功能可以傳送修改後的區塊、確認區塊 (不進行任何變更)，或刪除區塊。

Proxy 每次只會傳送少量資料。因此，擴充功能服務必須盡快確認區塊。

雖然無法動態變更主體模式，但進階擴充功能伺服器可以動態選取要接收的未來 HTTP 事件。在標頭要求期間傳回 ext_proc mode_override 選項，呼叫伺服器即可啟用或停用未來的標頭、主體或尾碼事件。

 要求必須包含 REQUEST_BODY，回應則必須包含 RESPONSE_BODY。 流量擴充功能 (適用於要求和回應)。
FULL_DUPLEX_STREAMED

通話會以全雙工模式執行。

Proxy 會在收到區塊時傳送，不會緩衝處理。由於沒有緩衝，Proxy 對擴充功能延遲時間的敏感度較低。

Proxy 可以視需要接收任意數量的回覆區塊。回覆區塊與 Proxy 傳送的區塊無關。後續區塊會在抵達 Proxy 時送交處理，不必等待先前的區塊和事件完全處理完畢。

擴充功能可以隨意緩衝、修改及重新分塊處理主體內容。如果擴充功能未傳回主體內容，鏈結中的下一個擴充功能就會收到空白主體。

ext_proc mode_override 選項不適用，且模式無法動態變更。

 要求必須包含 REQUEST_BODY 和 REQUEST_TRAILERS，回應則必須包含 RESPONSE_BODY 和 RESPONSE_TRAILERS。 流量擴充功能 (適用於要求和回應)。

路徑擴充功能 (適用於要求)。

使用者管理的叫用後端服務支援的後端

您可以在後端服務上代管使用者管理的叫用擴充功能，該後端服務使用下列其中一種後端，執行 Envoy gRPC 服務：

摘要的最佳化建議

將擴充功能整合至處理路徑，會導致要求和回應的延遲時間增加。擴充功能服務處理的每種資料 (包括要求標頭、要求內文、回應標頭和回應內文，視情況而定) 都會增加延遲。

請考慮進行下列最佳化設定，盡量縮短延遲時間：

  • 在與 Proxy 的一般目的地後端服務相同的區域中，部署回呼。

    使用跨區域內部應用程式負載平衡器時，請將擴充服務後端放在與負載平衡器僅限 Proxy 子網路相同的區域。

  • 使用全域外部應用程式負載平衡器時，請將回呼服務後端放在一般負載平衡器的目的地 VM、GKE 工作負載和 Cloud Run 函式所在的地理區域。

  • 盡可能將擴充功能設為只處理您需要的資料。舉例來說，如要只修改路徑和流量擴充功能的請求標頭，請將擴充功能中的 supported_events 欄位設為 REQUEST_HEADERS。

附註的限制

本節列出使用附註的幾項限制。

標頭操控的限制

部分標題無法變更。以下是標頭操控的限制：

  • 系統不支援對下列標頭進行標頭操控：

    • X-user-IP
    • CDN-Loop
    • 開頭為 X-Forwarded、X-Google、X-GFE 或 X-Amz- 的標題
    • connection
    • keep-alive
    • transfer-encoding、te
    • upgrade
    • proxy-connection、proxy-authenticate、proxy-authorization
    • trailers

    如果是流量和授權擴充功能，系統也不支援對下列項目進行標頭操控：:method、:authority、:scheme 或主機標頭。

  • 如果 gRPC 伺服器在 HeaderMutation 中指定標頭值，系統會忽略 value 欄位。

身體處理的限制

以下是 HTTP/1.1 用戶端和後端在郵件內文方面的限制，適用於 ext_proc，但不適用於 ext_authz。

  • 為擴充功能設定 REQUEST_BODY 或 RESPONSE_BODY 時，如果 Proxy 收到相符要求，就會從回應中移除 Content-Length 標頭，並切換為分塊主體編碼。

  • 將郵件內文串流至 ext_proc 伺服器時，Proxy 可能會在結尾傳送尾隨 ProcessingRequest 訊息，其中包含空白主體，並將 end_stream 設為 true，表示串流已結束。

其他限制

gRPC 回應訊息有下列限制：

  • 回應訊息的大小上限為 128 KB。如果收到的訊息超過此上限，系統會關閉串流並顯示 RESOURCE_EXHAUSTED 錯誤。

  • 呼叫後端服務無法使用 Cloud Armor、IAP 或 Cloud CDN 政策。

  • 叫用後端服務必須使用 HTTP/2 做為通訊協定。

  • 如果是授權擴充功能，負載平衡器不會將任何要求主體轉送至附註後端服務。

  • 如果是路徑擴充功能，呼叫後端服務無法覆寫 ext_proc 串流的處理模式。

後續步驟