外部処理ポリシー

ポリシー名

外部処理

Summary (概要)

追加処理を行うために、受信 HTTP 要求または送信 HTTP 応答要求を外部 gRPC サービスに送信します

カテゴリ

変換

使用可能な最小 Flex Gateway バージョン

v1.6.0

返される状況コード

403 - IP は拒否されました

概要

外部処理ポリシーでは、ヘッダー、トレーラー、本文、またはこの 3 つのいずれかの組み合わせを変更するために、受信 HTTP 要求または送信 HTTP 応答を外部 gRPC サービスに転送します。要求、応答、またはその両方を処理するようにこのポリシーを設定することもできます。

さらに、外部処理サービスでは最初の gRPC 要求が Flex Gateway によって外部処理サーバーに送信された後に HTTP 要求または応答の別の部分を要求できます。これにより、必要最小限の量のデータを送信できます。たとえば、Flex Gateway では最初に HTTP リクエストヘッダーのみを送信できます。その後、何らかの処理を行った後で、外部プロセッサーが Flex Gateway からの HTTP 要求の本文またはトレーラーを要求できます。

HTTP ヘッダー、トレーラー、本文について設定するパラメーターでは、最初に送信される内容のみが設定されます。外部処理サービスは、設定ないように関係なく、HTTP 要求または応答のすべての部分にアクセスできます。処理サービスがすべての受信 HTTP 要求または応答に必要なすべての情報を送信するようにパラメーターを設定します。たとえば、処理サービスにすべてのリクエストヘッダーが必要だが一部の要求の本文しか必要ない場合は、ヘッダーで確認できる情報に応じて、ヘッダーを送信するパラメーターのみを設定します。

外部処理ポリシーは、Envoy に対してネイティブな外部処理検索条件の拡張機能です。外部処理検索条件に付いての詳細は、「External Processing Filter (外部処理検索条件)」を参照してください。すべての外部処理検索条件パラメーターが外部処理ポリシーで使用できるとは限りません。設定可能なパラメーターを確認するには、「ポリシーのパラメーターの設定」を参照してください。

他のポリシーで HTTP 要求または応答が変更される場合は、要求が処理サービスまたはアップストリームサービスに送信されるときにこれらの変更が存在している必要があるかどうかに応じて確実にポリシーを並び替えてください。ポリシーの並び替えについての詳細は、ポリシーの順序付けを参照してください。

ポリシーのパラメーターの設定

Flex Gateway のローカルモード

ローカルモードでは、宣言型の設定ファイルを使用してポリシーを API に適用します。以下のポリシー定義とパラメーターの表を参照してください。

- policyRef:
    name: native-ext-proc-flex
  config:
    uri: <string> // REQUIRED
    messageTimeout: <integer> // OPTIONAL, default: 1000
    requestHeaderMode: <string> // OPTIONAL, default: "send"
    responseHeaderMode: <string> // OPTIONAL, default: "send"
    requestBodyMode: <string> // OPTIONAL, default: "none"
    responseBodyMode: <string> // OPTIONAL, default: "none"
    requestTrailerMode: <string> // OPTIONAL, default: "skip"
    responseTrailerMode: <string> // OPTIONAL, default: "skip"
    failureModeAllow: <boolean> // OPTIONAL, default: false
    maxMessageTimeout: <integer> // OPTIONAL, default: 0
    allowModeOverride: <boolean> // OPTIONAL, default: true

パラメーター必須または省略可能デフォルト値説明

パラメーター	必須または省略可能	デフォルト値	説明
`uri`	必須	なし	外部処理サーバー URI。gRPC 種別のサーバーでは、`\h2://<ext.authz.com>:<port>` として URI を定義します。
`messageTimeout`	省略可能	`1000`	処理サーバーのメッセージタイムアウト (ミリ秒)。
`maxMessageTimeout`	省略可能	0	処理サーバーが `messageTimeout` を上書きできる上限を指定します。
`failureModeAllow`	省略可能	`false`	`true` の場合、gRPC ストリームが早期に終了するか、開始できないと、要求の処理がエラーなしで続行されます。
`allowModeOverride`	省略可能	`true`	処理サーバーがポリシー設定を上書きできるようにします。`true` の場合、サーバーが `requestHeaderMode`、`responseHeaderMode`、`requestBodyMode`、`responseBodyMode`、`requestTrailerMode`、`responseTrailerMode` パラメーターの設定を上書きできます。
`observabilityMode`	省略可能	`false`	`true` の場合、設定されたヘッダー、本文、トレーラーが外部処理サーバーに送信され、Flex Gateway は処理サーバーからの応答を待ちません。
`requestHeaderMode`	省略可能	`send`	HTTP リクエストヘッダーが処理サービスに送信されるかどうか。サポートされている値は `send` と `skip` です。
`responseHeaderMode`	省略可能	`send`	HTTP レスポンスヘッダーが処理サービスに送信されるかどうか。サポートされている値は `send` と `skip` です。
`requestBodyMode`	省略可能	`none`	HTTP 要求の本文が送信されるモード。サポートされている値は、`none`、`streamed`、`buffered`、`bufferedPartial` です。`none` を選択すると、リクエストボディが送信されません。
`responseBodyMode`	省略可能	`none`	HTTP 応答の本文が送信されるモード。サポートされている値は、`none`、`streamed`、`buffered`、`bufferedPartial` です。`none` を選択すると、リクエストボディが送信されません。
`requestTrailerMode`	省略可能	`skip`	HTTP 要求のトレーラーヘッダーが処理サービスに送信されるかどうか。サポートされている値は `send` と `skip` です。
`responseTrailerMode`	省略可能	`skip`	HTTP 応答のトレーラーヘッダーが処理サービスに送信されるかどうか。サポートされている値は `send` と `skip` です。

uri

必須

なし

外部処理サーバー URI。gRPC 種別のサーバーでは、\h2://<ext.authz.com>:<port> として URI を定義します。

messageTimeout

省略可能

1000

処理サーバーのメッセージタイムアウト (ミリ秒)。

maxMessageTimeout

省略可能

処理サーバーが messageTimeout を上書きできる上限を指定します。

failureModeAllow

省略可能

false

true の場合、gRPC ストリームが早期に終了するか、開始できないと、要求の処理がエラーなしで続行されます。

allowModeOverride

省略可能

true

処理サーバーがポリシー設定を上書きできるようにします。true の場合、サーバーが requestHeaderMode、responseHeaderMode、requestBodyMode、responseBodyMode、requestTrailerMode、responseTrailerMode パラメーターの設定を上書きできます。

observabilityMode

省略可能

false

true の場合、設定されたヘッダー、本文、トレーラーが外部処理サーバーに送信され、Flex Gateway は処理サーバーからの応答を待ちません。

requestHeaderMode

省略可能

send

HTTP リクエストヘッダーが処理サービスに送信されるかどうか。サポートされている値は send と skip です。

responseHeaderMode

省略可能

send

HTTP レスポンスヘッダーが処理サービスに送信されるかどうか。サポートされている値は send と skip です。

requestBodyMode

省略可能

none

HTTP 要求の本文が送信されるモード。サポートされている値は、none、streamed、buffered、bufferedPartial です。none を選択すると、リクエストボディが送信されません。

responseBodyMode

省略可能

none

HTTP 応答の本文が送信されるモード。サポートされている値は、none、streamed、buffered、bufferedPartial です。none を選択すると、リクエストボディが送信されません。

requestTrailerMode

省略可能

skip

HTTP 要求のトレーラーヘッダーが処理サービスに送信されるかどうか。サポートされている値は send と skip です。

responseTrailerMode

省略可能

skip

HTTP 応答のトレーラーヘッダーが処理サービスに送信されるかどうか。サポートされている値は send と skip です。

値を空白のままにすると、パラメーターがデフォルト値を使用して設定されます。必須パラメーターにデフォルト値が設定されていない場合、パラメーターを設定する必要があります。

リソースの設定例

次の設定では、リクエストヘッダー、トレーラー、本文が外部処理サーバーに送信されます。次の設定では、応答はどの部分も外部処理サーバーに送信されません。

- policyRef:
    name: native-ext-proc-flex
  config:
    uri: h2://<ext.authz.com>:<port>
    messageTimeout: <integer> // OPTIONAL
    responseHeaderMode: skip
    requestBodyMode: streamed
    responseTrailerMode: skip

管理 Flex Gateway および Flex Gateway の接続モード

UI からポリシーを API インスタンスに適用するときに、以下のパラメーターが表示されます。

パラメーター説明

パラメーター	説明
External processing server URI (外部処理サーバー URI)	外部処理サーバー URI。gRPC 種別のサーバーでは、`\h2://<ext.authz.com>:<port>` として URI を定義します。
Message timeout (メッセージタイムアウト)	処理サーバーのメッセージタイムアウト (ミリ秒)。
Max message timeout (最大メッセージタイムアウト)	処理サーバーが [Message timeout (メッセージタイムアウト)] を上書きできる上限を指定します。
Failure mode allow (障害モードの許可)	`true` の場合、gRPC ストリームが早期に終了するか、開始できないと、要求の処理がエラーなしで続行されます。
Allow mode override (モードの上書きを許可)	処理サーバーがポリシー設定を上書きできるようにします。`true` の場合、サーバーは [Request header processing mode (リクエストヘッダーの処理モード)]、[Response header processing mode (レスポンスヘッダーの処理モード)]、[Request body processing mode (リクエストボディの処理モード)]、[Response body processing mode (レスポンスボディの処理モード)]、[Request trailer processing mode (リクエストトレーラーの処理モード)]、[Response trailer processing mode (レスポンストレーラーの処理モード)] パラメーターの設定を上書きできます。
Observability mode (オブザーバビリティモード)	有効にすると、設定されたヘッダー、本文、トレーラーが外部処理サーバーに送信され、Flex Gateway は処理サーバーからの応答を待機しません。
Request header processing mode (リクエストヘッダーの処理モード)	リクエストヘッダーが処理サービスに送信されるかどうか。
Response header processing mode (レスポンスヘッダーの処理モード)	レスポンスヘッダーが処理サービスに送信されるかどうか。
Request body processing mode (要求の本文の処理モード)	要求の本文が送信されるモード。
Response body processing mode (応答の本文の処理モード)	応答の本文が送信されるモード。
Request trailer processing mode (要求のトレーラーの処理モード)	要求のトレーラーが処理サービスに送信されるかどうか。
Response trailer processing mode (応答のトレーラーの処理モード)	応答のトレーラーが処理サービスに送信されるかどうか。

External processing server URI (外部処理サーバー URI)

外部処理サーバー URI。gRPC 種別のサーバーでは、\h2://<ext.authz.com>:<port> として URI を定義します。

Message timeout (メッセージタイムアウト)

処理サーバーのメッセージタイムアウト (ミリ秒)。

Max message timeout (最大メッセージタイムアウト)

処理サーバーが [Message timeout (メッセージタイムアウト)] を上書きできる上限を指定します。

Failure mode allow (障害モードの許可)

true の場合、gRPC ストリームが早期に終了するか、開始できないと、要求の処理がエラーなしで続行されます。

Allow mode override (モードの上書きを許可)

処理サーバーがポリシー設定を上書きできるようにします。true の場合、サーバーは [Request header processing mode (リクエストヘッダーの処理モード)]、[Response header processing mode (レスポンスヘッダーの処理モード)]、[Request body processing mode (リクエストボディの処理モード)]、[Response body processing mode (レスポンスボディの処理モード)]、[Request trailer processing mode (リクエストトレーラーの処理モード)]、[Response trailer processing mode (レスポンストレーラーの処理モード)] パラメーターの設定を上書きできます。

Observability mode (オブザーバビリティモード)

有効にすると、設定されたヘッダー、本文、トレーラーが外部処理サーバーに送信され、Flex Gateway は処理サーバーからの応答を待機しません。

Request header processing mode (リクエストヘッダーの処理モード)

リクエストヘッダーが処理サービスに送信されるかどうか。

Response header processing mode (レスポンスヘッダーの処理モード)

レスポンスヘッダーが処理サービスに送信されるかどうか。

Request body processing mode (要求の本文の処理モード)

要求の本文が送信されるモード。

Response body processing mode (応答の本文の処理モード)

応答の本文が送信されるモード。

Request trailer processing mode (要求のトレーラーの処理モード)

要求のトレーラーが処理サービスに送信されるかどうか。

Response trailer processing mode (応答のトレーラーの処理モード)

応答のトレーラーが処理サービスに送信されるかどうか。

ポリシーのしくみ

次の図は、外部処理ポリシーを適用した場合の要求と応答のフローの順序を示しています。

API インタラクションを示すフローチャート

クライアントが Flex Gateway に対する HTTP 要求を行います。
Flex Gateway が設定済みのクライアント HTTP 要求の最初の部分を外部処理サービスに転送します。[Observability mode (オブザーバビリティモード)] が有効になっていると、次のステップはスキップされます。
Flex Gateway は変更されたクライアント HTTP 要求を待機します。[Allow mode override (モードの上書きを許可)] が有効になっていると、外部処理サービスは要求の追加の部分を要求できます。
Flex Gateway はクライアント HTTP 要求をアップストリーム API サービスに送信し、HTTP 応答を待機します。
Flex Gateway が設定済みの HTTP 応答の最初の部分を外部処理サービスに転送します。[Observability mode (オブザーバビリティモード)] が有効になっていると、次のステップはスキップされます。
Flex Gateway は変更された HTTP 応答を待機します。[Allow mode override (モードの上書きを許可)] が有効になっていると、外部処理サービスは HTTP 応答の追加の部分を要求できます。
Flex Gateway が外部処理サービスからクライアントに変更済みの HTTP 応答を返します。

デフォルトでは、Flex Gateway が gRPC サービスへの接続を確立できない場合、または gRPC サービスでエラーが返される場合は、ポリシーが失敗します。接続やエラー状況に関係なく要求を転送するには、[Failure mode allow (障害モードの許可)] パラメーターを有効にします。