トラフィック拡張機能を構成する

Service Extensions を使用すると、サポートされているアプリケーション ロードバランサでプラグインを使用したり、バックエンド サービスにコールアウトを送信して、処理パスにカスタム処理を挿入したりできます。トラフィック拡張は、リクエスト処理パスの最後に実行され、レスポンス処理パスの最初に実行されて、バックエンド サービスの選択に影響を与えることなくヘッダーとペイロードを変更します。このページでは、トラフィック拡張機能を構成する方法について説明します。

アプリケーション ロードバランサの拡張機能の概要については、Cloud Load Balancing の拡張機能の概要をご覧ください。

アプリケーション ロードバランサのトラフィック拡張機能は、次のリソースを指します。

  • 関連付ける転送ルール
  • バックエンドが ext_proc gRPC API を実行するプラグインまたはコールアウト バックエンド サービス

トラフィック拡張機能は、関連する拡張機能サービスを 1 つ以上のチェーンにグループ化します。同じ拡張機能チェーンでプラグインとコールアウトの両方を構成できます。各拡張機能チェーンは、Common Expression Language（CEL）一致条件を使用して、処理するトラフィックを選択します。ロードバランサは、各チェーンの一致条件に対してリクエストを順番に評価します。リクエストがチェーンで定義された条件に一致すると、チェーン内のすべての拡張機能がリクエストに対して動作します。特定の要求に一致するチェーンは 1 つだけです。

チェーン内の各拡張機能は、独自のサポート対象イベントのセットを持つことができます。拡張機能によってリクエストとレスポンスのコンテンツに加えられた変更は、チェーン内の残りの拡張機能に表示されます。レスポンス イベントをサポートするように構成された拡張機能の場合、拡張機能のシーケンスはレスポンス パスで逆になります。

トラフィック拡張機能は、関連付けるロードバランサの転送ルールを参照します。リソースを構成すると、ロードバランサは一致するリクエストの拡張サービスへの送信を開始します。

拡張機能に関連する上限については、割り当てと上限のページをご覧ください。

プラグインを使用して構成する

このセクションでは、プラグインを使用してトラフィック拡張機能を構成する方法について説明します。

特定のプラグインを参照するすべての拡張機能リソースは同じ型である必要があります。拡張機能も同じロード バランシング スキームを使用する必要があります。Media CDN 拡張機能ですでに使用されているプラグインを使用して、Cloud Load Balancing 拡張機能を構成することはできません。

始める前に

  1. カスタムコードを含むプラグインを作成します。

  2. トラフィック拡張機能プラグインをサポートするアプリケーション ロードバランサを作成して構成します。

    たとえば、VM インスタンス グループのバックエンドを使用してグローバル外部アプリケーション ロードバランサを設定するをご覧ください。

  3. curl を実行するなど、サービスにテスト リクエストを送信する方法を設定します。内部ロードバランサを使用している場合は、テスト用のクライアント VM を作成します。

プラグインを使用してトラフィック拡張機能を構成する

次の例は、ホストが example.com と一致する場合にレスポンス ヘッダー hello: service-extensions を追加するプラグインを使用して、トラフィック拡張機能を構成する方法を示しています。

  1. URL マップに example.com と一致するものが存在するかどうかを確認します。

    1. クライアント VM の転送ルールに対して次の curl コマンドを実行します。

      curl -D - -H "host: example.com" FORWARDING_RULE_IP

      FORWARDING_RULE_IP は、転送ルールの IP アドレスに置き換えます。IP アドレスを確認するには、gcloud compute forwarding-rules describe コマンドを使用します。

      出力は次のようになります。

      HTTP/1.1 200 OK
...
content-length: 46
content-type: text/html
via: 1.1 google

  2. トラフィック拡張機能を構成します。

    コンソール

    1. Google Cloud コンソールで、[サービス拡張機能] ページに移動します。

      Service Extensions に移動

    2. [拡張機能を作成] をクリックします。

      ウィザードが開き、初期設定の手順が表示されます。

    3. プロダクトとして [ロード バランシング] を選択します。その後、[Continue] をクリックします。

      サポートされているアプリケーション ロードバランサのリストが表示されます。

    4. ロードバランサのタイプとして、グローバル外部アプリケーション ロードバランサまたはクロスリージョン内部アプリケーション ロードバランサのいずれかを選択します。その後、[続行] をクリックします。

    5. 拡張機能のタイプとして [トラフィック拡張機能] を選択し、[続行] をクリックします。

    6. [拡張機能を作成] フォームを開くには、[続行] をクリックします。

      [拡張機能の作成] フォームで、ページの上部に表示される前の選択内容は編集できないことに注意してください。

    7. [基本] セクションで、次の操作を行います。

      1. 拡張機能の一意の名前を指定します。

        名前は先頭を小文字にし、その後に 62 文字以下の小文字、数字、ハイフンを続けます。末尾をハイフンにすることはできません。

      2. 省略可: 1,024 文字以内で拡張機能の簡単な説明を入力します。

    8. 省略可: [ラベル] セクションで、[ラベルを追加] をクリックします。表示された行で、次の操作を行います。

      • [キー] にキー名を入力します。
      • [値] に、キーの値を入力します。

      Key-Value ペアをさらに追加するには、[ラベルを追加] をクリックします。最大 64 個の Key-Value ペアを追加できます。

      ラベルの詳細については、プロジェクトのラベルを作成、更新するをご覧ください。

    9. [転送ルール] で、拡張機能に関連付ける転送ルールを 1 つ以上選択します（例: http-content-rule）。

      別の拡張機能にすでに関連付けられている転送ルールは選択できず、使用不可と表示されます。

    10. [拡張機能] で、一致するリクエストに対して実行する拡張機能を追加する手順は次のとおりです。

      • 拡張機能チェーンが実行されるリクエストを照合するには、[一致条件] に Common Expression Language（CEL）式（request.host == "example.com" など）を指定します。

        CEL 式の詳細については、[構文のヘルプを表示] をクリックするか、CEL マッチャーの言語リファレンスをご覧ください。

      • [Programmability type] で [Plugins] を選択します。

      • [Plugin] で、同じプロダクトと拡張機能タイプ用にService Extensions を使用して作成されたプラグインを選択します。

      • [イベント] で、拡張機能を呼び出す 1 つ以上の HTTP イベントタイプを選択します。

      • [転送属性] で、ロードバランサが Wasm プラグインに転送するリクエスト、接続、ロケーションの属性を選択します。拡張機能ごとに最大 16 個の属性を構成できます。詳細については、サポートされている属性をご覧ください。

      • [ヘッダーを転送] で、[ヘッダーを追加] をクリックし、拡張機能に転送する HTTP ヘッダー（クライアントまたはバックエンドから）を追加します。ヘッダーが指定されていない場合は、すべてのヘッダーが送信されます。

      • 省略可: 拡張機能がタイムアウトまたは失敗した場合に、リクエストまたはレスポンスの処理を続行する場合は、[Fail open] で [有効] を選択します。チェーン内の後続の拡張機能も実行されます。

        デフォルトでは、[Fail open] オプションは選択されていません。この場合、エラーが発生すると、リクエストまたはレスポンスの処理が停止します。レスポンス ヘッダーがダウンストリーム クライアントに配信されていない場合、一般的な HTTP 500 ステータス コードがクライアントに返されます。レスポンス ヘッダーが配信されている場合、クライアントへの HTTP ストリームがリセットされます。

        セキュリティまたは完全性を優先する場合は、[フェイル オープン] を選択しないデフォルトのオプションが推奨されます。フェイルオープンを有効にすると、特に重要でないオペレーションで、可用性を優先する場合に役立ちます。

      単一の拡張機能ではなく、複数の拡張機能または拡張機能チェーンを指定する場合は、フォームの最後にある [詳細モードに切り替え] ボタンをクリックして、必要な拡張機能とチェーンを指定します。拡張機能は、リストに表示されている順序で実行されます。

      各拡張機能と拡張機能チェーンに一意の名前を指定します。名前は RFC-1034 に準拠している必要があります。小文字（英字）、数字、ハイフンのみで構成し、最大文字数は 63 文字です。また、先頭の文字は英字に、末尾の文字は英字または数字にする必要があります。

    11. [拡張機能を作成] をクリックします。

    gcloud

    1. YAML ファイルでプラグインを定義し、転送ルール（http-content-rule など）に関連付けます。

      cat >traffic-plugin.yaml <<EOF
    name: traffic-ext
    forwardingRules:
    - https://www.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/forwardingRules/http-content-rule
    loadBalancingScheme: EXTERNAL_MANAGED
    extensionChains:
    - name: "chain1"
      matchCondition:
        celExpression: 'request.host == "example.com"'
      extensions:
      - name: 'ext1'
        service: projects/PROJECT_ID/locations/LOCATION/wasmPlugins/WASM_PLUGIN
        failOpen: false
        supportedEvents:
        - RESPONSE_HEADERS
        forwardAttributes:
        - request.host
        - request.path
EOF

      次のように置き換えます。

      • PROJECT_ID: プロジェクト ID。
      • REGION: 転送ルールのリージョン。値は、プラグインのロケーションに指定された値と一致している必要があります。
      • LOCATION: プラグインのロケーション（global またはリージョン）。
      • WASM_PLUGIN: プラグインの ID または完全修飾名。

      YAML ファイルのフィールドの詳細については、API ドキュメントの ExtensionChain をご覧ください。

      forwardAttributes フィールドでは、Wasm プラグインに転送できるリクエスト、接続、ロケーションの属性を指定できます。拡張機能ごとに最大 16 個の属性を構成できます。サポートされている属性の詳細については、サポートされている属性をご覧ください。

    2. トラフィック拡張機能をインポートします。次のサンプル値を使用して、gcloud service-extensions lb-traffic-extensions import コマンドを使用します。

      gcloud service-extensions lb-traffic-extensions import traffic-ext \
    --source=traffic-plugin.yaml \
    --location=global

    トラフィック拡張機能が作成された後、新しいプラグインがすべてのロケーションに分散されるまでに少し時間がかかります。プラグインはすべての地域に同時に配信されるわけではないため、地域によって時間が異なる場合があります。

  3. トラフィック拡張機能が期待どおりに動作することを確認するには、同じ curl コマンドを使用します。

    curl -D - -H "host: example.com" FORWARDING_RULE_IP

    出力には hello: service-extensions レスポンス ヘッダーが含まれます。

    HTTP/1.1 200 OK
...
content-length: 46
content-type: text/
hello: service-extensions
via: 1.1 google

    拡張機能が example.com トラフィックのみをターゲットにしていることを検証するには、host ヘッダーなしで curl コマンドを繰り返します。

    curl -D - FORWARDING_RULE_IP

    出力は次のようになります。

    HTTP/1.1 200 OK
...
content-length: 46
content-type: text/html
via: 1.1 google

コールアウトを使用して、ユーザー管理サービスへのトラフィック拡張機能を構成する

このセクションでは、コールアウトを使用して、ユーザー管理のコールアウト バックエンド サービスにトラフィック拡張機能を構成する方法について説明します。

始める前に

コールアウト バックエンド サービスを構成するの説明に従って、必要なリソースを作成します。

コールアウトを使用してトラフィック拡張機能を構成する

次の例は、ホストが example.com と一致したときに呼び出すコールアウトを使用して、トラフィック拡張機能を構成する方法を示しています。callout-vm のトラフィック拡張機能サーバーは、一致するリクエストにレスポンス ヘッダー hello: service-extensions を追加します。

  1. URL マップに example.com と一致するものが存在するかどうかを確認します。

    1. クライアント VM の転送ルールに対して次の curl コマンドを実行します。

      curl -D - -H "host: example.com" FORWARDING_RULE_IP

      FORWARDING_RULE_IP は、転送ルールの IP アドレスに置き換えます。IP アドレスを確認するには、gcloud compute forwarding-rules describe コマンドを使用します。

      出力は次のようになります。

      HTTP/1.1 200 OK
...
content-length: 46
content-type: text/html
via: 1.1 google

Page served from: l7-ilb-backend-example-1c7t

  2. トラフィック拡張機能を構成します。

    コンソール

    1. Google Cloud コンソールで、[サービス拡張機能] ページに移動します。

      Service Extensions に移動

    2. [拡張機能を作成] をクリックします。

      ウィザードが開き、初期設定の手順が表示されます。

    3. プロダクトとして [ロード バランシング] を選択します。その後、[Continue] をクリックします。

      サポートされているアプリケーション ロードバランサのリストが表示されます。

    4. ロードバランサのタイプを選択します。リージョン ロードバランサの場合は、リージョンも指定します。[続行] をクリックします。

    5. 拡張機能のタイプとして [トラフィック拡張機能] を選択し、[続行] をクリックします。

    6. [拡張機能を作成] フォームを開くには、[続行] をクリックします。

      [広告表示オプションの作成] フォームでは、ページの上部に表示される前の選択内容を編集できないことに注意してください。

    7. [基本] セクションで、次の操作を行います。

      1. 拡張機能の一意の名前を指定します。

        名前は先頭を小文字にし、その後に 62 文字以下の小文字、数字、ハイフンを続けます。末尾をハイフンにすることはできません。

      2. 省略可: 1,024 文字以内で拡張機能の簡単な説明を入力します。

    8. 省略可: [ラベル] セクションで、[ラベルを追加] をクリックします。表示された行で、次の操作を行います。

      • [キー] にキー名を入力します。
      • [値] に、キーの値を入力します。

      Key-Value ペアをさらに追加するには、[ラベルを追加] をクリックします。最大 64 個の Key-Value ペアを追加できます。

      ラベルの詳細については、プロジェクトのラベルを作成、更新するをご覧ください。

    9. [転送ルール] で、拡張機能に関連付ける転送ルールを 1 つ以上選択します（例: l7-ilb-forwarding-rule）。

      別の拡張機能にすでに関連付けられている転送ルールは選択できず、使用不可と表示されます。

    10. [拡張機能] で、一致するリクエストに対して実行する拡張機能を追加する手順は次のとおりです。

      • [Programmability type] で [Callouts] を選択します。

      • 拡張機能チェーンが実行されるリクエストを照合するには、[一致条件] に Common Expression Language（CEL）式（request.host == "example.com" など）を指定します。

        CEL 式の詳細については、[構文のヘルプを表示] をクリックするか、CEL マッチャーの言語リファレンスをご覧ください。

      • [Authority] に、ロードバランサから拡張機能サービスに送信される gRPC リクエストの authority ヘッダーを入力します。

      • [バックエンド サービス] で、コールアウト バックエンド サービスを構成するの手順に沿って作成したバックエンド サービスを選択します。

      • [Timeout] に、ストリーム上のメッセージがタイムアウトするまでの時間（10 ～ 1, 000 ミリ秒）を指定します。

      • [イベント] で、拡張機能を呼び出す 1 つ以上の HTTP イベントタイプを選択します。

      • [転送属性] で、ロードバランサがコールアウト サービスに転送するリクエスト、接続、ロケーションの属性を選択します。拡張機能ごとに最大 16 個の属性を構成できます。詳細については、サポートされている属性をご覧ください。

      • [ヘッダーを転送] で、[ヘッダーを追加] をクリックし、拡張機能に転送する HTTP ヘッダー（クライアントまたはバックエンドから）を追加します。ヘッダーが指定されていない場合は、すべてのヘッダーが送信されます。

      • 省略可: 拡張機能がタイムアウトまたは失敗し、リクエストまたはレスポンスの処理を続行する場合は、[Fail open] で [有効] を選択します。チェーン内の後続の拡張機能も実行されます。

        デフォルトでは、[Fail open] オプションは選択されていません。この場合、エラーが発生すると、リクエストまたはレスポンスの処理が停止します。レスポンス ヘッダーがダウンストリーム クライアントに配信されていない場合、一般的な HTTP 500 ステータス コードがクライアントに返されます。レスポンス ヘッダーが配信されている場合、クライアントへの HTTP ストリームがリセットされます。

        セキュリティまたは完全性を優先する場合は、[フェイル オープン] を選択しないデフォルトのオプションが推奨されます。フェイルオープンを有効にすると、特に重要でないオペレーションで、可用性を優先する場合に役立ちます。

      • [メタデータ] で [メタデータを追加] をクリックし、提案されたサンプル値を指定します。[キー] に key を指定し、[値] に value を指定します。

        別の Key-Value ペアを追加するには、[メタデータを追加] をクリックします。[キー] に fr を指定し、[値] に forwarding_rule_id を指定します。

        [メタデータ] フィールドでは、ロードバランサから拡張機能サーバーに追加情報を渡すことができます。メタデータは ProcessingRequest メッセージで送信され、protobuf.Struct としてエンコードされます。メタデータ内で指定された転送ルール ID と一致するテキストは、クライアント リクエストに関連付けられた転送ルールの完全修飾リソース URL に置き換えられます。

        メタデータの合計サイズは 1 KiB 未満である必要があります。メタデータのキーの合計数は 20 個未満にする必要があります。各キーの長さは 64 文字未満にする必要があります。各値の長さは 1,024 文字未満でなければなりません。すべての値は文字列にする必要があります。

      単一の拡張機能ではなく、複数の拡張機能または拡張機能チェーンを指定する場合は、フォームの最後にある [詳細モードに切り替え] ボタンをクリックして、必要な拡張機能とチェーンを指定します。拡張機能は、リストに表示されている順序で実行されます。

      各拡張機能と拡張機能チェーンに一意の名前を指定します。名前は RFC-1034 に準拠している必要があります。小文字（英字）、数字、ハイフンのみで構成し、最大文字数は 63 文字です。また、先頭の文字は英字に、末尾の文字は英字または数字にする必要があります。

    11. [拡張機能を作成] をクリックします。

    gcloud

    1. YAML ファイルでコールアウトを定義し、転送ルールに関連付けます。提供されているサンプル値を使用します。

      cat >traffic.yaml <<EOF
    name: traffic-ext
    forwardingRules:
    - https://www.googleapis.com/compute/v1/projects/PROJECT_ID/regions/us-west1/forwardingRules/l7-ilb-forwarding-rule
    loadBalancingScheme: INTERNAL_MANAGED
    extensionChains:
    - name: "chain1"
      matchCondition:
        celExpression: 'request.host == "example.com"'
      extensions:
      - name: 'ext11'
        authority: ext11.com
        service: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/regions/us-west1/backendServices/l7-ilb-callout-service
        failOpen: false
        timeout: 0.1s
        metadata:
          "key": "value"
          "fr": "forwarding_rule_id"
        supportedEvents:
        - RESPONSE_HEADERS
        forwardAttributes:
        - request.host
        - request.path
EOF

      PROJECT_ID は、プロジェクト ID に置き換えます。

      拡張機能構成の metadata フィールドを使用すると、ロードバランサから拡張機能サーバーに追加情報を渡すことができます。メタデータは ProcessingRequest メッセージで送信され、protobuf.Struct としてエンコードされます。メタデータ内の指定された転送ルール ID と一致するテキストは、クライアント リクエストに関連付けられた転送ルールの完全修飾リソース URL に置き換えられます。

      metadata の合計サイズは 1 KiB 未満にする必要があります。メタデータのキーの合計数は 16 未満にする必要があります。各キーの長さは 64 文字未満にする必要があります。各値の長さは 1,024 文字未満でなければなりません。すべての値は文字列にする必要があります。

      YAML ファイルのフィールドの詳細については、API ドキュメントの ExtensionChain をご覧ください。

      forwardAttributes フィールドでは、コールアウト サービスに転送するリクエスト、接続、ロケーションの属性を指定できます。拡張機能ごとに最大 16 個の属性を構成できます。サポートされている属性の詳細については、サポートされている属性をご覧ください。

    2. トラフィック拡張機能をインポートします。次のサンプル値を使用して、gcloud service-extensions lb-traffic-extensions import コマンドを使用します。

      gcloud service-extensions lb-traffic-extensions import traffic-ext \
    --source=traffic.yaml \
    --location=us-west1

  3. トラフィック拡張機能が想定どおりに機能することを確認します。同じ curl コマンドを使用します。

    curl -D - -H "host: example.com" FORWARDING_RULE_IP

    出力には hello: service-extensions レスポンス ヘッダーが含まれます。

    HTTP/1.1 200 OK
...
content-length: 46
content-type: text/
hello: service-extensions
via: 1.1 google

Page served from: l7-ilb-backend-example-1c7t

    拡張機能が example.com トラフィックのみをターゲットにしていることを検証するには、host ヘッダーなしで curl コマンドを繰り返します。

    curl -D - FORWARDING_RULE_IP

    出力は次のようになります。

    HTTP/1.1 200 OK
...
content-length: 46
content-type: text/html
via: 1.1 google

Page served from: l7-ilb-backend-example-1c7t

次のステップ