プラグインの概要

このページでは、プラグインと Cloud Load Balancing アプリケーション ロードバランサおよび Media CDN の統合の概要について説明します。

この機能は Media CDN のプレビュー版です。

プラグインは WebAssembly（Wasm）形式を使用して構築され、Proxy-Wasm API を使用します。

  • Wasm は、ホストが顧客提供のコードで Wasm モジュールを読み込んで実行できるようにする、オープンで標準化されたバイナリ命令形式です。Wasm には、セキュリティのためのサンドボックス化、複数の言語のサポート、移植性、業界内での広範かつ拡大するサポート、JavaScript などの他の VM ベースのオプションと比較してパフォーマンスの向上など、顧客コードの実行に多くのメリットがあります。

  • Proxy-Wasm は、Google が開始したオープンソース プロジェクトです。HTTP リクエストとレスポンスの処理中に実行されるコールバックを実装することで、ネットワーク プロキシの動作をカスタマイズできる API を定義します。

プラグインの仕組み

アプリケーション ロードバランサと Media CDN で Service Extensions を使用する方法は次のとおりです。

  1. 次のようにプラグイン コードを準備します。

    1. Proxy-Wasm SDK のいずれかを使用してカスタムコードを作成します。

    2. コードを Wasm モジュールにコンパイルします。

    3. コンパイルされたプラグイン コードを Artifact Registry リポジトリにアップロードします。

  2. アップロードされたプラグイン コードを含むプラグインを作成します。

  3. Cloud Load Balancing 拡張機能または Media CDN 拡張機能でプラグインを構成します。

プラグイン リソース

Service Extensions は、処理パスにカスタムコードを追加するのに役立つ次のキーリソースの作成に役立ちます。

  • デプロイするカスタムコードを含むプラグイン。

  • プラグインのバージョン: Wasm モジュールのバージョン。プラグインがメイン（アクティブ）として使用する Wasm モジュールのバージョンを指定できます。

プラグインで属性にアクセスする

Wasm プラグインは、Proxy-Wasm ABI の一部である proxy_get_property 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 のメモリを使用できます。インスタンスは最大 1, 000 個の同時リクエストを処理できる必要があります。つまり、プラグインはストリームごとに最大 16 KiB のメモリを保持できます。メモリ使用量の合計には、グローバル状態とスタック割り当てが含まれることに注意してください。

プラグイン テスターを使用して、プラグインの 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 ヘッダーを削除し、チャンク本文エンコードに切り替えます。

次のステップ