ルート拡張機能を構成する

Service Extensions を使用すると、サポートされているアプリケーション ロードバランサでプラグインを使用したり、バックエンド サービスにコールアウトを送信して、処理パスにカスタム処理を挿入したりできます。ルート拡張機能は、ロードバランサがリクエスト ヘッダーを受信したとき、および URL マップを評価する前に、リクエスト処理パスで実行されます。このページでは、ルート拡張機能を構成する方法について説明します。

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

アプリケーション ロードバランサのルート拡張機能は、次のリソースを参照します。

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

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

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

アプリケーション ロードバランサ拡張機能に関連する上限については、割り当てと上限のページをご覧ください。

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

このセクションでは、パスが /extensions と一致する場合に :host リクエスト ヘッダーを service-extensions.com に書き換えるプラグインを使用して、ルート拡張機能を構成する方法を例で示します。以前のホストと新しく構成されたホストは、異なるリージョンのバックエンド サービスにマッピングされます。これはルーティング動作を示しています。

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

始める前に

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

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

    VM インスタンス グループのバックエンドを使用してクロスリージョン内部アプリケーション ロードバランサを設定するページの次の手順を除くすべての手順に沿って操作します。

    • バックエンド サービスに service-one という名前を付けます。
    • service-one をリージョン A の仮想マシン（VM）インスタンスに転送します。
    • デフォルトで gl7-gilb-url-map を service-one に設定します。

  3. 追加のバックエンド サービス service-two を設定し、リージョン B の VM を指すようにします。

  4. URL マップに、service-two を指すパスマッチャーを追加します。次のサンプル値を使用して、gcloud compute url-maps add-path-matcher コマンドを使用します。

      gcloud compute url-maps add-path-matcher gl7-gilb-url-map \
      --path-matcher-name=rewrite-host \
      --default-service=service-two \
      --new-hosts=service-extensions.com \
      --location=global

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

プラグインを使用してルート拡張機能を構成する

  1. 拡張機能が構成される前の動作を確認します。

    1. 明示的なパスのないリクエストがリージョン A に送信されることを確認します。

      curl FORWARDING_RULE_IP

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

      出力は次のようになります。これは、ページが region A の VM から提供されていることを示しています。

      Page served from region-A-vm

    2. URL マップに /extensions の一致がないことを確認します。

      curl FORWARDING_RULE_IP/extensions

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

      この出力は、URL マップに /extensions と一致するものが存在しないことを示しています。出力は次のようになります。

      <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
<html><head>
<title>404 Not Found</title>
</head><body>
...

  2. ルート拡張機能を構成します。

    コンソール

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

      サービス拡張機能に移動

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

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

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

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

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

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

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

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

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

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

        名前は、先頭が英小文字で、その後に最大 62 文字の英小文字、数字、ハイフンで構成します。末尾をハイフンにすることはできません。

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

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

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

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

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

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

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

    9. 拡張機能チェーンの場合は、一致したリクエストに対して実行する 1 つ以上の拡張機能チェーンを追加します。

      拡張機能チェーンを追加するには、次の操作を行ってから [完了] をクリックします。

      • [新しい拡張チェーン] に一意の名前を指定します。

        名前は RFC-1034 に準拠している必要があります。小文字（英字）、数字、ハイフンのみで構成し、最大文字数は 63 文字です。また、先頭の文字は英字に、末尾の文字は英字または数字にする必要があります。

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

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

      • 一致したリクエストに対して実行する拡張機能を追加します。ルート拡張機能では、1 つの拡張機能のみを指定できます。

        [拡張機能] で、次の操作を行ってから [完了] をクリックします。

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

        • [拡張機能名] に、一意の名前を指定します。

          名前は RFC-1034 に準拠している必要があります。小文字（英字）、数字、ハイフンのみで構成し、最大文字数は 63 文字です。また、先頭の文字は英字に、末尾の文字は英字または数字にする必要があります。

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

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

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

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

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

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

    gcloud

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

      cat >route-plugin.yaml <<EOF
    name: route-ext
    forwardingRules:
    - https://www.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/forwardingRules/cr-ilb-forwarding-rule
    loadBalancingScheme: INTERNAL_MANAGED
    extensionChains:
    - name: "chain1"
      matchCondition:
        celExpression: 'request.path.startsWith("/extensions")'
      extensions:
      - name: 'ext1'
        service: projects/PROJECT_ID/locations/LOCATION/wasmPlugins/WASM_PLUGIN
        failOpen: false
        supportedEvents:
        - REQUEST_HEADERS
EOF

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

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

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

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

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

  3. ルート拡張機能が想定どおりに機能することを確認するには、同じ curl コマンドを使用します。

    curl FORWARDING_RULE_IP/extensions

    出力は次のようになります。これは、ページが region B の VM から提供されていることを示しています。

    Page served from region-B-vm

    プラグインが /extension パス接頭辞を持つリクエストに対してのみ実行されることを確認するには、パスを指定せずに curl コマンドを繰り返します。

    curl FORWARDING_RULE_IP

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

    Page served from region-A-vm

コールアウトを使用して構成する

このセクションでは、コールアウトを使用してルート拡張機能を構成する方法について説明します。

始める前に

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

コールアウトを使用してルート拡張機能を構成する

次の例は、パスが /extensions と一致したときに呼び出すルート拡張機能を構成する方法を示しています。callout-vm のルート コールアウト サーバーは、Host ヘッダーを service-extensions.com に変更し、パスを / に設定してから、ルートを再計算するようロードバランサに指示を送信します。トラフィックは l7-ilb-backend-service ではなく l7-ilb-backend-service2 に流れます。

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

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

      curl FORWARDING_RULE_IP/extensions

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

      この出力は、URL マップに /extensions と一致するものが存在しないことを示しています。出力は次のようになります。

      <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
<html><head>
<title>404 Not Found</title>
</head><body>
...

  2. ルート拡張機能を構成します。

    コンソール

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

      サービス拡張機能に移動

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

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

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

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

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

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

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

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

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

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

        名前は、先頭が英小文字で、その後に最大 62 文字の英小文字、数字、ハイフンで構成します。末尾をハイフンにすることはできません。

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

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

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

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

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

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

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

    9. 拡張機能チェーンの場合は、一致したリクエストに対して実行する 1 つ以上の拡張機能チェーンを追加します。

      拡張機能チェーンを追加するには、次の操作を行ってから [完了] をクリックします。

      • [新しい拡張チェーン] に一意の名前を指定します。

        名前は RFC-1034 に準拠している必要があります。小文字（英字）、数字、ハイフンのみで構成し、最大文字数は 63 文字です。また、先頭の文字は英字に、末尾の文字は英字または数字にする必要があります。

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

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

      • 一致したリクエストに対して実行する拡張機能を追加します。ルート拡張機能には、1 つの拡張機能のみを指定できます。

        [拡張機能] で、次の操作を行ってから [完了] をクリックします。

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

        • [拡張機能名] に、一意の名前を指定します。

          名前は RFC-1034 に準拠している必要があります。小文字（英字）、数字、ハイフンのみで構成し、最大文字数は 63 文字です。また、先頭の文字は英字に、末尾の文字は英字または数字にする必要があります。

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

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

        • [タイムアウト] には、10 ～ 1,000 ミリ秒の値を指定します。この値を超えると、ロードバランサが ext_proc サービスからのレスポンスを待機している間に、ストリーム上のメッセージがタイムアウトします。

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

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

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

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

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

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

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

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

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

    gcloud

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

      cat >route.yaml <<EOF
    name: route-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.path.startsWith("/extensions")'
      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"
EOF

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

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

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

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

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

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

    curl FORWARDING_RULE_IP/extensions

    この出力は、元のリクエストは一致しなかったものの、トラフィックが仮想ホスト service-extensions.com と一致し、l7-ilb-backend-service2 サービスに到達したことを示しています。出力は次のようになります。

    Page served from second backend service

    コールアウトが /extension プレフィックス付きのリクエストのみをターゲットにしていることを検証するには、path プレフィックスなしで curl コマンドを繰り返します。

    curl FORWARDING_RULE_IP

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

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

ルート拡張機能の制限事項

  • ルート拡張機能は HTTP 本文の処理をサポートしていません。
  • ルート拡張機能では、拡張機能からクライアントへの直接レスポンスはサポートされていません。ルート拡張サーバーが、直接レスポンスを含む処理レスポンスで処理リクエストに応答した場合、ロードバランサは処理レスポンスを無視します。

すべての拡張機能に適用される制限事項については、拡張機能の制限事項をご覧ください。

次のステップ