4.2. 3scale 標準ポリシーからのポリシーチェーン

4.2.1. APIcast NGINX フェーズが 3scale ポリシーを処理する仕組み

3scale API ゲートウェイ (APIcast) は、NGINX プロキシー Web サーバーを使用してポリシーを適用します。APIcast が API 利用者からリクエストを受け取ると、APIcast は要求を一連の NGINX フェーズの順番どおりに処理します。それぞれの NGINX フェーズでは、APIcast は以下のポリシーを適用して元のリクエストを変更することができます。

アップストリーム API ポリシーチェーンのポリシー。ポリシーチェーンは、順番が設定されたポリシーのリストです。デフォルトでは、アップストリーム API のポリシーチェーンには 3scale APIcast ポリシーが含まれます。API プロバイダーは、3scale プロダクトのポリシーチェーンにポリシーを追加することができます。APIcast は、アップストリーム API ポリシーチェーンのポリシーを、そのアップストリーム API に送信された API 利用者のリクエストだけに適用します。
グローバル 3scale ポリシーチェーンのポリシー。API プロバイダーは、3scale の環境変数を設定して、グローバルポリシーチェーンを更新することができます。APIcast は、グローバルポリシーチェーンのポリシーをすべての API 利用者のリクエストに適用します。

同じポリシーがアップストリーム API のポリシーチェーンおよびグローバルポリシーチェーンにある場合は、アップストリーム API のポリシーチェーンのポリシー設定が優先されます。

APIcast がすべての NGINX フェーズの必要な処理を行った後に、APIcast はリクエストの結果をアップストリーム API に送信します。そのため、処理によって API 利用者のリクエストを変更できるため、希望の動作を実現するには、NGINX フェーズがポリシーを処理する順序を理解することが重要です。

NGINX フェーズの順序と説明

APIcast が API 利用者からリクエストを受け取ると、APIcast はアップストリーム API のポリシーチェーンおよびグローバルポリシーチェーンのポリシーを適用してリクエストを処理します。各 3scale ポリシーは 1 つ以上の関数を定義します。APIcast は、一連の NGINX フェーズの順番どおりにポリシーの関数を実行します。各フェーズでは、NGINX は適用されるポリシーで定義され、そのフェーズでの実行を指定する関数を実行します。以下の表は、ポリシー関数を実行する NGINX のフェーズのリストを示しています。この表に記載されていない追加の NGINX フェーズは、ポリシーチェーン内のポリシーの順序によって影響を受けない処理を実行します。

NGINX フェーズのリスト	このフェーズでの処理の説明
`rewrite`	要求のターゲット URI を変更する関数を実行します。
`access`	リクエストを行うためのクライアントの承認を検証する関数を実行します。
`content`	アップストリーム API に送信されるリクエストのコンテンツを生成します。 NGINX は、`content` フェーズ内の 1 つのポリシーのみを適用します。ポリシーチェーン内の複数のポリシーがリクエストのコンテンツで動作する場合、NGINX はチェーン内で最も早いポリシーのみを適用します。組み込みの 3scale APIcast ポリシーは常にポリシーチェーンにあり、`content` フェーズで NGINX の処理が必要になるため、これを理解することが重要です。たとえば、3scale APIcast ポリシーと Upstream ポリシーの両方が、リクエストを更新してアップストリーム API のパスを指定します。NGINX は、これらの関数を `content` フェーズで処理します。3scale APIcast ポリシーが Upstream ポリシーの前にある場合、NGINX はアップストリーム API の設定を使用して、そのパスを修正したリクエストに追加します。Upstream ポリシーが 3scale APIcast ポリシーの前にある場合には、NGINX は Upstream ポリシーの式を評価します。一致がある場合、NGINX は修正したリクエストで適宜アップストリーム API のパスを変更します。
`balancer`	負荷分散関数を実行します。
`header_filter`	リクエストヘッダーを処理する関数を実行します。
`body_filter`	リクエストボディーを処理する関数を実行します。
`post_action`	NGINX がヘッダーとボディーで関数を実行した後にリクエストを処理する関数を実行します。
`log`	リクエストに関するログ情報を生成します。
`metrics`	Prometheus エンドポイントから受信されるデータで機能します。

ポリシーの順序によって影響を受けない処理を実行する NGINX フェーズの例:

APIcast が起動すると、NGINX は init フェーズに関連付けられたタスクを実行します。
APIcast ワーカーが起動すると、NGINX は init_worker フェーズに関連付けられたタスクを実行します。
APIcast が HTTPS 接続を終了すると、NGINX は ssl_certificate フェーズに関連付けられたタスクを実行します。

NGINX がポリシー関数を実行する順序

API プロバイダーは、1 つ以上のポリシーを 3scale プロダクトに追加してポリシーチェーンを形成できます。各フェーズでは、NGINX はそのフェーズでの実行を指定するポリシー関数のみを処理します。各ポリシー関数は、1 つの NGINX フェーズでの処理中に APIcast がそのデフォルトの動作をどのように変更するかを指定します。たとえば、header_filter フェーズでは、NGINX は header_filter を指定し、リクエストヘッダーで操作する関数を処理します。各フェーズでは、NGINX は、ポリシーチェーンにある順序で該当する関数を処理します。

ポリシーは、context オブジェクトを使用してデータを共有できます。ポリシーは、各フェーズで context オブジェクトを読み取ったり、変更したりできます。

NGINX がポリシー関数を実行する順序は、以下の要素によって異なります。

ポリシーチェーンでのポリシーの位置
特定のポリシー関数を処理する NGINX フェーズ

必要な動作を得るには、ポリシーチェーンの順序を正しく指定する必要があります。ポリシー適用の結果は、ポリシーチェーン内の位置により異なる可能性があるためです。以下の図は、NGINX がポリシーを適用する順序の例を示しています。

上の図では、ポリシー A がポリシーチェーンの最初のものです。しかし、NGINX は、まずポリシー B の関数を処理します。その関数が NGINX の最初のフェーズである rewrite フェーズに関連するためです。

ここで、以下の関数を持つポリシー A およびポリシー B が含まれるプロダクトのポリシーチェーンについて検討します。

ポリシー A は以下を指定します。
- access フェーズで実行する NGINX の関数 A1
- header_filter フェーズで実行する NGINX の関数 A2
ポリシー B は以下を指定します。
- rewrite フェーズで実行する NGINX の関数 B1
- header_filter フェーズで実行する NGINX の関数 B2

以下の図は、NGINX がプロダクトのポリシー関数を実行する順序を示しています。

APIcast NGINX 実行フェーズおよびサンプル 3scale ポリシーチェーン

APIcast がこのプロダクトにより公開されるアップストリーム API へのアクセスリクエストを受け取ると、APIcast はプロダクトのポリシーチェーンを確認し、以下の表で説明するように関数を実行します。

NGINX フェーズのリスト	NGINX が各フェーズで実行する機能
`rewrite`	ポリシー B が `rewrite` フェーズに指定する関数 `B1` を実行します。
`access`	ポリシー A が `access` フェーズに指定する関数 `A1` を実行します。
`content`	ポリシー A とポリシー B のいずれも、`content` フェーズで実行する関数を指定しません。
`balancer`	ポリシー A とポリシー B のいずれも、`balancer` フェーズで実行する関数を指定しません。
`header_filter`	ポリシーチェーンはポリシー A を指定し、次にポリシー B を指定します。したがって、このフェーズは、ポリシー A が `header_filter` フェーズに指定する関数 `A2` を実行し、続いてポリシー B が `header_filter` フェーズに指定する関数 `B2` を実行します。
`body_filter`	ポリシー A とポリシー B のいずれも、このフェーズで実行する関数を指定しません。
`post_action`	ポリシー A とポリシー B のいずれも、このフェーズで実行する関数を指定しません。
`log`	ポリシー A とポリシー B のいずれも、このフェーズで実行する関数を指定しません。

この例では、ポリシー A がポリシーチェーンの最初のものですが、ポリシー B の関数が NGINX が実行する最初の関数です。これは、ポリシー B が NGINX が (他のフェーズよりも前にある) rewrite フェーズで処理する関数 B1 を指定するためです。

別の例として、以下のポリシーチェーンについて考えてみましょう。

URL Rewriting
3scale APIcast (すべてのプロダクトに割り当てられたデフォルトポリシー)

URL Rewriting ポリシーは、リクエストのターゲットパスを変更します。APIcast は rewrite フェーズで URL Rewriting 関数を実行します。3scale APIcast ポリシーは、APIcast が rewrite フェーズで実行する関数に加えて、APIcast が他の 3 つのフェーズで実行する関数を定義します。URL Rewriting ポリシーが最初になると、3scale APIcast ポリシーにより、書き換えられたパスにマッピングルールが適用されます。3scale APIcast ポリシーが最初にあり、URL Rewriting ポリシーが 2 番目の場合には、3scale APIcast ポリシーにより、元のパスにマッピングルールが適用されます。

関連情報

4.2.2. 3scale 管理ポータルでのポリシーチェーンの変更

APIcast ゲートウェイ設定の一部として、3scale 管理ポータルでプロダクトのポリシーチェーンを変更します。

手順

3scale にログインします。
ポリシーチェーンを設定する API プロダクトに移動します。
[your_product_name] > Integration > Policies の順に移動し、Add policy をクリックします。
Policy Chain セクションで、矢印アイコンを使用してポリシーチェーン内のポリシーの順番を変更します。
Update Policy Chain をクリックし、ポリシーチェーンを保存します。

次のステップ

管理ポータルの左側のナビゲーションパネルに、APIcast にプロモートしていない設定変更があることを示す警告が表示されるようになりました。ポリシーチェーンの更新をステージング APIcast にプロモートし、必要に応じて更新をテストします。必要な動作を確認したら、更新を実稼働 APIcast にプロモートします。APICAST_CONFIGURATION_CACHE 環境変数をゼロより大きい数 (デフォルト) に設定すると、APIcast が更新された設定を使用するまでにその秒数かかります。

4.2.3. JSON 設定ファイルでの 3scale ポリシーチェーンの作成

APIcast のネイティブデプロイメントを使用している場合には、JSON 設定ファイルを作成して、外部でポリシーチェーンを制御することができます。

ポリシーチェーン JSON 設定ファイルには、以下の情報で設定される JSON 配列が含まれます。

services オブジェクト (id の値 (ポリシーチェーンが適用されるサービスを指定する数字) が含まれる)
proxy オブジェクト (policy_chain オブジェクトおよび下位オブジェクトが含まれる)
policy_chain オブジェクト (ポリシーチェーンを定義する値が含まれる)
個々の policy オブジェクト (ポリシーを識別しポリシーの動作を設定するのに必要な name および configuration データの両方を指定する)

カスタムポリシー sample_policy_1 および標準の API イントロスペクションポリシー token_introspection で設定されるポリシーチェーンの例を、以下に示します。

{
  "services":[
    {
      "id":1,
      "proxy":{
        "policy_chain":[
          {
            "name":"sample_policy_1", "version": "1.0",
            "configuration":{
              "sample_config_param_1":["value_1"],
              "sample_config_param_2":["value_2"]
            }
          },
          {
            "name": "token_introspection", "version": "builtin",
            "configuration": {
              introspection_url:["https://tokenauthorityexample.com"],
              client_id:["exampleName"],
              client_secret:["secretexamplekey123"]
          },
          {
             "name": "apicast", "version": "builtin",
          }
        ]
      }
    }
  ]
}

すべてのポリシーチェーンには、内蔵のポリシー apicast を含める必要があります。apicast ポリシーをポリシーチェーンのどこに設定したかによって、ポリシーの動作が変わります。

4.2.4. 3scale 標準ポリシー関数を実行する NGINX フェーズ

以下の表は、メインの NGINX フェーズおよび NGINX がそのフェーズで実行する関数を定義する標準ポリシーのリストを示しています。この表には、NGINX が処理する順序でフェーズが記載されています。

ポリシーチェーンには、NGINX が特定のフェーズで処理するポリシーを複数含めることができます。このような場合には、チェーン内のポリシーの順序が、API リクエストを処理して希望の結果を取得するための正しい順序になるようにしてください。この表では、ポリシーをアルファベット順でリスト表示します。

NGINX フェーズのリスト	このフェーズで処理される関数を定義する標準ポリシー
`rewrite`	3scale APIcast 3scale Referrer Anonymous Access Echo Header Modification NGINX Filter SOAP Upstream URL Rewriting URL Rewriting with Captures Websocket
`access`	3scale APIcast 3scale Batcher Camel Proxy Content Caching Edge Limiting IP Check JWT Claim Check RH-SSO/Keycloak Role Check Maintenance Mode OAuth 2.0 Mutual TLS Client Authentication OAuth 2.0 Token Introspection Rate Limit Headers Response/Request Content Limits Routing TLS Client Certificate Validation Upstream
`content`	3scale APIcast Liquid Context Debug Rate Limit Headers Routing Upstream
`balancer`	Upstream Mutual TLS
`header_filter`	CORS Request Handling Header Modification Response/Request Content Limits HTTP Response Code Overwrite
`body_filter`	Response/Request Content Limits
`post_action`	3scale APIcast Custom metrics
`log`	Edge Limiting Logging

関連情報

4.2.5. 3scale 標準ポリシーおよびそれらのポリシーを処理する NGINX フェーズ

以下の表は、標準ポリシーと、そのポリシーの関数を実行する NGINX フェーズまたはフェーズのリストを示しています。この表を使用してポリシーチェーンでポリシーを正しい順序で設定し、アップストリーム API の正しいリクエストを生成します。

標準ポリシー	ポリシー関数を実行する NGINX フェーズ
3scale APIcast	`init` `rewrite` `access` `content` `post_action` APIcast は、3scale APIcast ポリシーをすべてのリクエストに適用します。
Anonymous Access	`rewrite`
3scale Auth Caching	ポリシーチェーンでは、このポリシーの位置は問題ではありません。
3scale Batcher	`access`
3scale Referrer	`rewrite`
Camel Service	`access`
Conditional ポリシー	ポリシーチェーンでは、このポリシーの位置は問題ではありません。
Content Caching	`access`
CORS Request Handling	`header_filter`
Custom metrics	`post_action`
Echo	`rewrite`
Edge Limiting	`access` `log`
Header Modification	`rewrite` `header_filter`
HTTP Response Code Overwrite	`header_filter`
IP Check	`access`
JWT Claim Check	`access`
Liquid Context Debug	`content`
Logging	`log`
Maintenance Mode	`access`
NGINX Filter	`rewrite`
OAuth 2.0 Mutual TLS Client Authentication	`access`
OAuth 2.0 Token Introspection	`access`
Proxy Service	ポリシーチェーンでは、このポリシーの位置は問題ではありません。
Rate Limit Headers	`access` +`content`
Response/Request Content Limits	`access` `header_filter` `body_filter`
Retry	ポリシーチェーンでは、このポリシーの位置は問題ではありません。
RH-SSO/Keycloak Role Check	`access`
Routing	`access` `content`
SOAP	`rewrite`
TLS Client Certificate Validation	`access`
TLS Termination	`ssl_certificate`
Upstream	`rewrite` `access` `content`
Upstream Connection	ポリシーチェーンでは、このポリシーの位置は問題ではありません。
Upstream Mutual TLS	`balancer`
URL Rewriting	`rewrite`
URL Rewriting with Captures	`rewrite`
Websocket	`rewrite`

関連情報

4.2. 3scale 標準ポリシーからのポリシーチェーン

4.2.1. APIcast NGINX フェーズが 3scale ポリシーを処理する仕組み

4.2.2. 3scale 管理ポータルでのポリシーチェーンの変更

4.2.3. JSON 設定ファイルでの 3scale ポリシーチェーンの作成

4.2.4. 3scale 標準ポリシー関数を実行する NGINX フェーズ

4.2.5. 3scale 標準ポリシーおよびそれらのポリシーを処理する NGINX フェーズ

詳細情報

試用、購入および販売

コミュニティー

Red Hat ドキュメントについて

多様性を受け入れるオープンソースの強化

会社概要

Red Hat legal and privacy links

Red Hat legal and privacy links