Cloud Load Balancing のコールアウトの概要

Service Extensions を使用すると、ロード バランシング データパスからユーザー管理のコールアウト サービスまたは Google サービスにコールアウトを送信するように、サポートされているアプリケーション ロードバランサに指示できます。

吹き出しのデータフロー

ロードバランサは、次のいずれかの Envoy gRPC プロトコルを使用してコールアウトと通信します。

  • 外部処理または ext_proc プロトコル。

    このプロトコルは、ルート、トラフィック、認可の拡張機能でサポートされており、デフォルトで使用されます。

    ext_proc プロトコルを使用すると、拡張サービスはリクエストのヘッダーまたは本文を検査して変更することで、HTTP リクエストのライフサイクル内のイベントに応答できます。

  • 外部認可または ext_authz プロトコル。

    このプロトコルは、認可拡張機能でのみサポートされています。ext_authz のサポートはプレビュー版です。

    ext_authz プロトコルは、受信リクエストの認可の決定を外部の独立したサービスに委任します。この API を使用すると、拡張機能サービスは、リクエストのヘッダーまたはメタデータを調べて、複雑な認可判断を行う HTTP リクエストのライフサイクル内のイベントに応答できます。

    このプロトコルは、認可拡張機能を構成するときに wireFormat オプションで指定できます。

これらの拡張サービスは、仮想マシン（VM）インスタンスまたは GKE にデプロイできます。また、これらのサービスのエンドポイントを表すようにインスタンス グループまたはネットワーク エンドポイント グループ（NEG）を構成できます。

次の図は、VM インスタンスや Google Kubernetes Engine（GKE）クラスタなどのユーザー管理のコンピューティング リソースに gRPC サーバーを使用してコールアウト バックエンド サービスをデプロイし、通常のバックエンド サービスとしてロードバランサに表す方法を示しています。

アプリケーション ロードバランサは、コールアウトを使用して、コールアウト バックエンド サービスからカスタム ロジックを含めます。
アプリケーション ロードバランサは、コールアウト バックエンド サービスを呼び出すために Service Extensions コールアウトを送信します（クリックして拡大）。

ext_proc でのコールアウトの仕組み

ext_proc gRPC API の短縮版は次のとおりです。

// The gRPC API to be implemented by the external processing server
service ExternalProcessor {
  rpc Process(stream ProcessingRequest) returns (stream ProcessingResponse) {
  }
}

// Envoy sets one of these fields depending on the processing stage.
message ProcessingRequest {
  oneof request {
    HttpHeaders request_headers = 2;
    HttpHeaders response_headers = 3;
    HttpBody request_body = 4;
    HttpBody response_body = 5;
  }
}

message ProcessingResponse {
  oneof response {
    HeadersResponse request_headers = 1;
    HeadersResponse response_headers = 2;
    BodyResponse request_body = 3;
    BodyResponse response_body = 4;

    ImmediateResponse immediate_response = 7;
  }
}

HTTP リクエストのヘッダーを受信すると、ロードバランサは ProcessingRequest メッセージを拡張サービスに送信します。このとき、request_headers フィールドはクライアントからの HTTP ヘッダーに設定されます。

拡張サービスは、ProcessingRequest メッセージのヘッダーまたは本文に構成された変更を含む、対応する ProcessingResponse メッセージで ProcessingRequest メッセージに応答する必要があります。また、サービスは immediate_response フィールドを設定して、ロードバランサがリクエスト処理を終了し、指定されたレスポンスをクライアントに送信するようにすることもできます。

REQUEST_HEADER イベントと RESPONSE_HEADER イベントの場合、拡張機能サービスはリクエストまたはレスポンスの HTTP ヘッダーを操作できます。サービスは、ProcessingResponse メッセージの request_headers フィールドまたは response_headers フィールドを適切に設定することで、ヘッダーの追加、変更、削除を行うことができます。ヘッダーには raw_value フィールドを使用します。

トラフィック拡張機能を使用すると、リクエストとレスポンスの両方のヘッダーと本文を変更できます。拡張機能サーバーは処理モードを動的にオーバーライドし、リクエスト処理の後続フェーズで拡張機能を有効または無効にできます。ロードバランサは、トラフィック拡張機能を呼び出した後にルートルールを再評価しません。

エッジ、認可、ルートの拡張機能は HTTP ヘッダーのみをサポートします。これらの拡張機能は、HTTP 本文を検査または変更できません。

ext_authz でのコールアウトの仕組み

ext_authz API は、認可コールアウト拡張機能のみをサポートします。

API の省略形は次のとおりです。

// A generic interface for performing authorization checks on incoming
// requests to a networked service.
service Authorization {
  // Performs an authorization check based on the attributes associated with
  // the incoming request and return status.
  rpc Check(CheckRequest) returns (CheckResponse) {
  }
}

message CheckRequest {
  // The request attributes.
  AttributeContext attributes = 1;
}

message CheckResponse {
  google.rpc.Status status = 1;
  oneof http_response {
    DeniedHttpResponse denied_response = 2;
    OkHttpResponse ok_response = 3;
  }
  google.protobuf.Struct dynamic_metadata = 4;
}

HTTP リクエストのヘッダーを受信すると、ロードバランサは拡張機能サービスに CheckRequest メッセージを送信します。

拡張機能サービスは、CheckRequest メッセージに対して、次の情報を含む対応する CheckResponse メッセージで応答する必要があります。

  • status: ステータスを示します。OK は、リクエストが許可されていることを示します。それ以外のステータスは、リクエストが拒否されたことを示します。

  • denied_response または ok_response: レスポンスが許可されたか拒否されたかを示します。このフィールドには、認可チェックに関連する HTTP レスポンス属性が伴います。

    • ok_response フィールドは、認可サービスがリクエストを許可するときに使用されます。このサービスは、元のリクエスト ヘッダーを変更、追加、削除し、クライアントに送信される HTTP レスポンス ヘッダーを更新できます。ヘッダーには raw_value フィールドを使用します。

    • denied_response フィールドは、認可サービスがリクエストを拒否した場合に使用されます。サービスは、クライアントに送信される HTTP レスポンス ヘッダーを更新できます。

    拡張機能サービスが CheckResponse メッセージで許可されていないヘッダー名または値を返した場合、リクエストは 500 Internal Error ステータス コードで拒否されます。許可されていないヘッダーについては、ヘッダー操作に関する制限事項をご覧ください。

  • dynamic_metadata: 認可拡張機能の後に呼び出される拡張機能（トラフィック拡張機能など）で使用されるオプションのメタデータが含まれます。

本文の処理モード

本文処理をサポートする拡張機能では、request_body_send_mode フィールドまたは response_body_send_mode フィールドの値を設定することで、リクエストとレスポンスの本文処理用に次の 2 つの送信モードのいずれかを構成できます。

デフォルト モードは STREAMED で、ほとんどのユースケースで推奨されます。

モード 説明 サポートされているイベントが必要 サポートされている拡張機能
STREAMED

呼び出しはストリーミング モードで実行されます。このデフォルト設定は、モードが設定されていない場合にも使用されます。

プロキシは、本文チャンクを拡張サービスに送信し、チャンクごとに 1 つのレスポンスを想定します。拡張機能は、変更されたチャンクを送信し直したり、変更なしでチャンクを承認したり、チャンクを削除したりできます。

プロキシは一度に送信するデータ量を制限します。そのため、拡張機能サービスはできるだけ早くチャンクを認識する必要があります。

ボディモードは動的に変更できませんが、高度な拡張機能サーバーは、受信する将来の HTTP イベントを動的に選択できます。ヘッダー リクエスト中に ext_proc mode_override オプションを返すことで、コールアウト サーバーは今後のヘッダー、本文、トレーラー イベントを有効または無効にできます。

 リクエストの場合は REQUEST_BODY、レスポンスの場合は RESPONSE_BODY を含める必要があります。 トラフィック拡張機能（リクエストとレスポンスの両方）。
FULL_DUPLEX_STREAMED

通話は全二重モードで実行されます。

プロキシはチャンクが到着するとすぐに送信し、バッファリングしません。バッファリングがないため、プロキシは拡張機能のレイテンシの影響を受けにくくなります。

プロキシは、必要に応じて多くの返信チャンクを受信できます。返信チャンクは、プロキシが送信するチャンクから切り離されます。後続のチャンクは、前のチャンクとイベントが完全に処理されるのを待たずに、プロキシに到着した時点で処理のために送信されます。

拡張機能は、本文の内容を自由にバッファリング、変更、再チャンクできます。拡張機能が本文の内容を返さない場合、チェーン内の次の拡張機能は空の本文を受け取ります。

ext_proc mode_override オプションは適用されず、モードを動的に変更することはできません。

 リクエストの場合は REQUEST_BODY と REQUEST_TRAILERS、レスポンスの場合は RESPONSE_BODY と RESPONSE_TRAILERS を含める必要があります。 トラフィック拡張機能（リクエストとレスポンスの両方）。

ルート拡張機能（リクエスト用）。

ユーザー管理のコールアウト バックエンド サービスでサポートされているバックエンド

Envoy gRPC サービスを実行する次のいずれかのタイプのバックエンドを使用するバックエンド サービスで、ユーザー管理のコールアウト拡張機能をホストできます。

コールアウト表示オプションの推奨される最適化

拡張機能をロード バランシング処理パスに統合すると、リクエストとレスポンスのレイテンシが追加されます。拡張機能サービスが処理する各タイプのデータ（リクエスト ヘッダー、リクエスト本文、レスポンス ヘッダー、レスポンス本文など）は、レイテンシを追加します。

レイテンシを最小限に抑えるには、次の最適化を検討してください。

  • ロードバランサの通常の宛先バックエンド サービスと同じゾーンにコールアウトをデプロイします。クロスリージョン内部アプリケーション ロードバランサを使用する場合は、ロードバランサのプロキシ専用サブネットと同じリージョンに拡張サービス バックエンドを配置します。
  • グローバル外部アプリケーション ロードバランサを使用する場合は、通常のロードバランサの宛先 VM、GKE ワークロード、Cloud Run functions がある地理的リージョンにコールアウト サービス バックエンドを配置します。
  • 可能な場合は、必要なデータのみを処理するように拡張機能を構成します。たとえば、ルート拡張機能とトラフィック拡張機能のリクエスト ヘッダーのみを変更するには、拡張機能の supported_events フィールドを REQUEST_HEADERS に設定します。

制限事項

このセクションでは、コールアウトに関する制限事項をいくつか示します。

ヘッダー操作の制限事項

一部のヘッダーは変更できません。ヘッダー操作には次の制限があります。

  • 次のヘッダーではヘッダー操作はサポートされていません。

    • X-user-IP
    • CDN-Loop
    • X-Forwarded、X-Google、X-GFE、X-Amz- で始まるヘッダー
    • connection
    • keep-alive
    • transfer-encoding、te
    • upgrade
    • proxy-connection、proxy-authenticate、proxy-authorization
    • trailers

    トラフィック拡張機能と認可拡張機能では、:method、:authority、:scheme、ホストヘッダーのヘッダー操作もサポートされていません。

  • gRPC サーバーが HeaderMutation でヘッダー値を指定すると、ロードバランサは value フィールドを無視します。

本文の処理に関する制限事項

メッセージ本文に関する HTTP/1.1 クライアントとバックエンドの制限事項は次のとおりです。これは ext_proc には適用されますが、ext_authz には適用されません。

  • 拡張機能に REQUEST_BODY または RESPONSE_BODY のいずれかを構成すると、ロードバランサは一致するリクエストを受信した場合、レスポンスから Content-Length ヘッダーを削除し、チャンク化されたボディ エンコードに切り替えます。

  • メッセージ本文を ext_proc サーバーにストリーミングしている間、最後に、ロードバランサは、ストリームが終了したことを示すために、end_stream が true に設定された空の本文を含む末尾の ProcessingRequest メッセージを送信する場合があります。

その他の制限

gRPC レスポンス メッセージには次の制限があります。

  • レスポンス メッセージの最大サイズは 128 KB です。受信したメッセージがこの上限を超えると、ストリームは RESOURCE_EXHAUSTED エラーで閉じられます。

  • コールアウト バックエンド サービスでは、Cloud Armor、IAP、Cloud CDN のポリシーを使用できません。

  • コールアウト バックエンド サービスは、プロトコルとして HTTP/2 を使用する必要があります。

  • 認可拡張機能の場合、ロードバランサはリクエスト本文をコールアウト バックエンド サービスに転送しません。

  • ルート拡張機能の場合、コールアウト バックエンド サービスは ext_proc ストリームの処理モードをオーバーライドできません。

次のステップ