外掛程式總覽

本頁面提供外掛程式與 Cloud Load Balancing 應用程式負載平衡器和 Media CDN 整合的總覽資訊。

這項功能為 Media CDN 的預先發布版。

外掛程式是以 WebAssembly (Wasm) 格式建構，並使用 Proxy-Wasm API。

  • Wasm 是一種開放且標準化的二進位指令格式，可讓主機載入及執行 Wasm 模組，並使用客戶提供的程式碼。Wasm 在執行客戶程式碼方面有許多優點，包括沙箱機制可確保安全性、支援多種語言、可攜性、業界廣泛且日益增加的支援，以及相較於其他以虛擬機器 (VM) 為基礎的選項 (例如 JavaScript)，效能有所提升。

  • Proxy-Wasm 是 Google 發起的開放原始碼專案，它定義了 API，可讓您透過實作回呼，在 HTTP 要求和回應處理期間執行，藉此自訂網路 Proxy 的行為。

外掛程式的運作方式

您可以搭配使用 Service Extensions 與應用程式負載平衡器和 Media CDN，如下所示：

  1. 按照下列步驟準備外掛程式程式碼：

    1. 使用其中一個 Proxy-Wasm SDK 建立自訂程式碼：

    2. 將程式碼編譯成 Wasm 模組。

    3. 將編譯好的外掛程式程式碼上傳至 Artifact Registry 存放區。

  2. 建立外掛程式，並加入上傳的外掛程式程式碼。

  3. 在 Cloud Load Balancing 擴充功能或 Media CDN 擴充功能中設定外掛程式。

外掛程式資源

Service Extensions 可協助您建立下列重要資源，以便在處理路徑中新增自訂程式碼：

  • 外掛程式：包含您要部署的自訂程式碼。

  • 外掛程式版本：Wasm 模組的版本。您可以指定外掛程式要將哪個版本的 Wasm 模組做為主要 (有效) 模組。

存取外掛程式中的屬性

Wasm 外掛程式可以使用 proxy_get_property ABI 呼叫 (Proxy-Wasm ABI 的一部分) 存取轉送的屬性。可擷取的屬性名稱會對應至屬性名稱。

您可以將屬性名稱表示為路徑，藉此存取屬性。舉例來說，如要擷取 request.host，可以使用 {"request", "host"} 等路徑表示法。

以下 Rust 概念範例說明如何在 HttpContext 實作中存取轉送的屬性：

use proxy_wasm::traits::{HttpContext, RootContext};
use proxy_wasm::types::Action;

// ... inside your HttpContext implementation ...

fn on_request_headers(&mut self, _num_headers: usize, _end_of_stream: bool) -> Action {
    if let Some(host) = self.get_property(vec!["request", "host"]) {
        // host is a Vec, convert to string
        let host_str = String::from_utf8(host).unwrap_or_default();
        log::info!("Request host: {}", host_str);
    }

    if let Some(region) = self.get_property(vec!["source", "client_region"]) {
        let region_str = String::from_utf8(region).unwrap_or_default();
        log::info!("Client region: {}", region_str);
    }

    Action::Continue
}

限制

本節列出外掛程式的一些限制。

資源限制

外掛程式可使用的資源數量受到嚴格限制：

  • 外掛程式每次叫用最多可使用 1 毫秒的標準化 vCPU。CPU 毫秒會因平台而異，但標準化平台大約等同於時脈速度為 4 GHz 的處理器。叫用是獨立計費的執行階段，可以是要求標頭、要求主體、回應標頭或回應主體。

  • 每個 VM 執行個體最多可使用 16 MiB 的外掛程式記憶體 (Media CDN 外掛程式為 4 MiB)。

    • 執行個體必須能同時處理最多 1,000 個並行要求，也就是說，外掛程式最多可為每個串流保留 16 KiB 的記憶體 (媒體 CDN 外掛程式為 4 KiB)。記憶體總用量包括全域狀態和堆疊分配。超過這項限制的外掛程式會遭到終止。

    • 建議您使用 C++ 和 Rust，因為這兩種語言產生的外掛程式記憶體用量最小。不建議將 Go SDK 用於 Media CDN，因為 Go 執行階段和垃圾收集器需要至少 2 至 3 MiB 的記憶體用量。

使用外掛程式測試工具，對外掛程式的 CPU 和記憶體特性進行基準測試。

API 限制

  • 外掛程式可以使用 Proxy-Wasm ABI 的子集。外掛程式不支援計時器、自訂指標、共用資料、共用待播清單或傳出網路呼叫。

  • 不支援 HTTP 結尾事件。

標頭操控限制

  • 任何異動 (標頭或主體區塊) 的大小上限為 128 KiB。

  • 外掛程式無法覆寫 ext_proc 串流的處理模式。

  • 部分標頭不支援透過外掛程式操控標頭。處理器會忽略這些標頭中的任何修改，並繼續處理要求。

    Media CDN 外掛程式不支援下列項目：

    • 標頭：CDN-Loop、connection、keep-alive、proxy-authenticate、proxy-authorization、proxy-connection、te、trailers、transfer-encoding、upgrade 或 X-user-IP。
    • 開頭為 x-forwarded、x-goog-、x-google、x-gfe 或 x-amz- 的標頭。

    Cloud Load Balancing 外掛程式不支援下列項目：

    • 標頭：connection、keep-alive、proxy-authenticate、proxy-authorization、proxy-connection、sec-user-ip、te、trailer、transfer-encoding、upgrade、x-dont-count-ads、x-dont-show-ads、x-gr、x-proxyuser-ip 或 x-user-ip。

      此外，LbTrafficExtension 也不支援下列標頭：method、authority、scheme 或主機標頭。

    • 開頭為 sec-gfe-、sec-google-、x-amz-、x-forwarded-、x-gfe-、x-goog-、x-google- 或 x-gproxy- 的標頭。

HTTP/1.1 用戶端和後端的限制

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

後續步驟