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

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

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

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

ルート拡張機能とトラフィック拡張機能の場合、拡張機能の observabilityModeがtrueに設定され、本文処理モード がSTREAMED（デフォルト）の場合、コールアウトは非同期で実行できます。拡張機能のバックエンドへの呼び出しは、進行中のリクエストの処理を一時停止することなく、非同期で行われます。 レスポンスは無視されます。

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 関数が配置されている地理的リージョンにコールアウト サービス バックエンドを配置します。
  • 可能な場合は、必要なデータのみを処理するように拡張機能を構成します。たとえば、ルート拡張機能とトラフィック拡張機能のリクエスト ヘッダーのみを変更するには、拡張機能の 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 ストリームの処理モードをオーバーライドできません。

次のステップ