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

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. コンソールで、[Service Extensions] ページに移動します。 Google Cloud

      Service Extensions に移動

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

      ウィザードが開き、初期手順を案内します。

    3. プロダクトとして [ロード バランシング] を選択します。次に、[続行] をクリックします。

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

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

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

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

      [拡張機能を作成] フォームでは、ページの上部に表示される前の選択内容は編集できません。

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

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

        名前は英小文字で始まり、最大 62 文字の英小文字、数字、ハイフンで構成します。ハイフンで終わることはできません。

      2. 省略可: 最大 1,024 文字を使用して、拡張機能の簡単な説明を入力します。

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

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

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

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

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

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

    10. [**拡張機能**] で、一致する リクエストに対して実行する拡張機能を追加するには、次の操作を行います。

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

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

      • [**プログラマビリティ タイプ**] で [**プラグイン**] を選択します。

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

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

      • [**転送属性**] で、拡張機能で転送する属性を選択します。詳細については、 サポートされている属性をご覧ください。

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

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

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

        セキュリティまたは整合性を優先する場合は、[Fail open] を選択しないデフォルト オプションをおすすめします。 特に重要でないオペレーションで [Fail open]を有効にすると、 可用性を優先する場合に役立ちます。

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

      各拡張機能と拡張機能チェーンに一意の名前を指定します。名前は 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 をご覧ください。サポートされている属性については、 サポートされている属性をご覧ください。

    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. コンソールで、[Service Extensions] ページに移動します。 Google Cloud

      Service Extensions に移動

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

      ウィザードが開き、初期手順を案内します。

    3. プロダクトとして [ロード バランシング] を選択します。次に、[続行] をクリックします。

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

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

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

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

      [拡張機能を作成] フォームでは、ページの上部に表示される前の選択内容は編集できません。

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

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

        名前は英小文字で始まり、最大 62 文字の英小文字、数字、ハイフンで構成します。ハイフンで終わることはできません。

      2. 省略可: 最大 1,024 文字を使用して、拡張機能の簡単な説明を入力します。

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

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

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

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

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

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

    10. [**拡張機能**] で、一致する リクエストに対して実行する拡張機能を追加するには、次の操作を行います。

      • [**プログラマビリティ タイプ**] で [**コールアウト**] を選択します。

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

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

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

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

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

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

      • [**転送属性**] で、拡張機能で転送する属性を選択します。詳細については、 サポートされている属性をご覧ください。

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

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

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

        セキュリティまたは整合性を優先する場合は、[Fail open] を選択しないデフォルト オプションをおすすめします。 特に重要でないオペレーションで [Fail open]を有効にすると、 可用性を優先する場合に役立ちます。

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

        [メタデータを追加] をクリックして、別の Key-Value ペアを追加します。 [Key] に fr を指定し、[Value] に 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 をご覧ください。サポートされている属性については、 サポートされている属性をご覧ください。

    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

次のステップ