プラグインの概要

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

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

プラグインは WebAssembly（Wasm）形式でビルドされ、Proxy-Wasm API を使用します。

• Wasm は、オープンで標準化されたバイナリ命令形式です。これにより、ホストは、お客様が提供したコードを使用して Wasm モジュールを読み込んで実行できます。Wasm には、セキュリティのためのサンドボックス化、複数の言語のサポート、ポータビリティ、業界内での幅広いサポートの拡大、仮想マシン（VM）に基づく他のオプション（JavaScript など）と比較したパフォーマンスの向上など、お客様のコードを実行するうえで多くのメリットがあります。

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

プラグインの仕組み

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

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

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

      • Rust

      • Go

      • C++

   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 のメモリを使用できます（Media CDN プラグインの場合は 4 MiB）。

  • インスタンスは最大 1,000 件の同時リクエストを処理できる必要があります。つまり、プラグインはストリームごとに最大 16 KiB のメモリを保持できます（Media CDN プラグインの場合は 4 KiB）。合計メモリ使用量には、グローバル状態とスタック割り当てが含まれます。この上限を超えたプラグインは終了します。

  • メモリ使用量が最も少ないプラグインを生成する C++ と Rust を使用することをおすすめします。Go ランタイムとガベージ コレクタには 2 ～ 3 MiB の最小ベースライン メモリ使用量が必要なため、Media CDN に Go SDK を使用することはおすすめしません。

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

次のステップ

• プラグイン コードを準備する
• プラグインを作成する