コールアウトの概要

Service Extensions を使用すると、ネットワーキング プロキシからコールアウトを作成できます。コールアウト拡張機能は、ほとんどのアプリケーション ロードバランサでサポートされています。コールアウト拡張機能は、Secure Web Proxy（プレビュー版）でもサポートされています。

吹き出しのデータフロー

ネットワーキング プロキシは、次のいずれかの Envoy gRPC プロトコルを使用して、コールアウトと通信します。

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

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

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

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

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

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

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

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

デプロイ シナリオの例

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

アプリケーション ロードバランサは、コールアウトを使用して、コールアウト バックエンド サービスのカスタム ロジックを含めます。
アプリケーション ロードバランサは、コールアウト バックエンド サービスを呼び出すために 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 リクエストのヘッダーを受信すると、アプリケーション ロードバランサと Secure Web Proxy のプロキシは、request_headers フィールドがクライアントからの HTTP ヘッダーに設定された ProcessingRequest メッセージを拡張サービスに送信します。

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

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

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

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

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

コールアウトの属性にアクセスする

ext_proc プロトコルを使用するコールアウト拡張機能の場合、構成された属性は ProcessingRequest メッセージで送信されます。属性は通常、envoy.filters.http.ext_proc などのキーの下にあるマップ フィールドに保存されます。

マップ内のキーは、拡張機能構成の forwardAttributes フィールドで指定した属性名に対応しています。

次の例は、ProcessingRequest.attributes の構造を示しています。

attributes {
  key: "envoy.filters.http.ext_proc"
  value {
    fields {
      key: "request.host"
      value { string_value: "example.com" }
    }
    fields {
      key: "source.client_region"
      value { string_value: "US" }
    }
    // ... other forwarded attributes
  }
}

gRPC サービス実装では、受信した ProcessingRequest メッセージのマップからこれらの値にアクセスできます。

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 ストリームの処理モードをオーバーライドできません。

次のステップ