docker: Cannot connect to the Docker daemon.Is the docker daemon running on this host? というエラーメッセージが表示された場合には、Docker サービスが起動していない可能性があります。sudo systemctl status docker.service コマンドを実行して、Docker デーモンのステータスを確認することができます。

RHEL で Docker コンテナー環境の操作を行う場合、デフォルトでは root 権限が必要なので、このコマンドは必ず root ユーザーとして実行してください。詳細については、このドキュメント を参照してください。

デタッチモードでコンテナーを起動し (-d オプション)、実行中の APIcast インスタンスのログを確認する場合には、log コマンド (sudo docker logs <container>) を使用することができます。ここで、<container> はコンテナー名 (上記の例ではapicast) またはコンテナー ID です。sudo docker ps コマンドを使用して、実行中のコンテナーならびにその ID および名前を一覧表示することができます。

コンテナーを停止するには、sudo docker stop <container> コマンドを実行します。sudo docker rm <container> コマンドを実行して、コンテナーを削除することもできます。

使用できるコマンドの詳細は、Docker コマンドのリファレンス を参照してください。

管理ポータルでは、3scale API プロダクトごとに 1 つ以上のポリシーを有効にすることができます。

3scale Auth Caching ポリシーは、APIcast に送信された認証呼び出しをキャシュします。動作モードを選択して、キャッシュ操作を設定することができます。

3scale Auth Caching では、以下のモードを使用することができます。

1.strict: 承認された呼び出しだけをキャッシュします。

strict モードでは、承認された呼び出しだけがキャッシュされます。ポリシーを strict モードで実行中に呼び出しが失敗または拒否されると、ポリシーはキャッシュエントリーを無効にします。バックエンドにアクセスできなくなると、キャッシュステータスにかかわらず、キャッシュされたすべての呼び出しが拒否されます。

2.resilient: バックエンドの機能が停止している場合には、最後のリクエストに基づいて承認します。

resilient モードでは、承認された呼び出しおよび拒否された呼び出しの両方がキャッシュされます。ポリシーを resilient モードで実行中は、呼び出しに失敗しても既存のキャッシュエントリーは無効になりません。バックエンドにアクセスできなくなると、キャッシュにヒットする呼び出しは、キャッシュステータスに応じて承認/拒否の状態を維持します。

3.allow: バックエンドの機能が停止している場合には、過去に拒否されていない限りすべてを許可します。

allow モードでは、承認された呼び出しおよび拒否された呼び出しの両方がキャッシュされます。ポリシーを allow モードで実行中は、キャッシュされた呼び出しはキャッシュステータスに応じて拒否/許可の状態を維持します。ただし、新規の呼び出しは承認された呼び出しとしてキャッシュされます。

4.none: キャッシュを無効にします。

none モードでは、キャッシュが無効になります。ポリシーを有効にしたままキャッシュの使用を止める場合に、このモードが役立ちます。

設定プロパティー

ポリシーオブジェクトの例

{
  "name": "caching",
  "version": "builtin",
  "configuration": {
    "caching_type": "allow"
  }
}

ポリシーの設定方法に関する情報は、このドキュメントの 3scale でのポリシーチェーンの作成 セクションを参照してください。

標準の APIcast 承認メカニズムでは、APIcast が API リクエストを受け取るたびに、3scale バックエンド (Service Management API) に対して 1 回呼び出しが行われます。3scale Batcher ポリシーは、この標準メカニズムの代替手段を提供します。

3scale Batcher ポリシーを使用すると、承認ステータスがキャッシュされ使用状況レポートがバッチ処理されます。これにより、3scale バックエンドへのリクエスト数が大幅に削減されます。3scale Batcher ポリシーにより、レイテンシーを短縮しスループットを増やすことで、API キャストのパフォーマンスを改善できます。

3scale Batcher ポリシーが有効な場合には、APIcast は以下のフローを使用して承認を行います。

3scale Batcher ポリシーではスループットが向上しますが、精度は低下します。使用上限および現在の使用状況は 3scale に保存され、APIcast は 3scale バックエンドに呼び出しを行う時にのみ正しい承認ステータスを取得することができます。3scale Batcher ポリシーが有効な場合には、APIcast が 3scale に呼び出しを送信しない期間があります。この期間中に、呼び出しを行うアプリケーションが定義された限度を超える可能性があります。

流量制御の精度よりもスループットが重要な場合には、高負荷の API に対してこのポリシーを使用します。報告頻度および承認の TTL が流量制御の期間よりはるかに短い場合には、3scale Batcher ポリシーにより優れた精度が得られます。たとえば、流量制御が 1 日あたりで、報告頻度および承認の TTL が数分に設定されている場合などです。

3scale Batcher ポリシーでは、以下の設定設定がサポートされます。

3scale Referrer ポリシーを使用すると、参照元フィルター 機能が有効になります。サービスポリシーチェーンでこのポリシーが有効な場合には、APIcast は上流への AuthRep コールとして 3scale Referrer ポリシーの値をService Management API に送信します。3scale Referrer ポリシーの値は、呼び出しの referrer パラメーターで送信されます。

参照元フィルター機能の仕組みの詳細については、認証パターンの 参照元フィルター セクションを参照してください。

Anonymous Access ポリシーでは、認証をせずにサービスが公開されます。このポリシーは、認証パラメーターを送信するように変更することのできないレガシーアプリケーション等の場合に有用です。Anonymous Access ポリシーは、API キーおよびアプリケーション ID/アプリケーションキーによる認証オプションだけを使用するサービスをサポートします。クレデンシャルをまったく持たない API リクエストに対してこのポリシーを有効にした場合には、APIcast はポリシーで設定されたデフォルトのクレデンシャルを使用して呼び出しを承認します。API の呼び出しが承認されるためには、クレデンシャルが設定されたアプリケーションが存在しアクティブでなければなりません。

アプリケーションプランを使用して、デフォルトのクレデンシャルに使用されるアプリケーションに流量制御を設定することができます。

ポリシーに必要な設定プロパティーを以下に示します。

図4.1 Anonymous Access ポリシー

Camel Service ポリシーを使用して、定義した Apache Camel プロキシーを使用して 3scale のトラフィックを送信する HTTP プロキシー を定義することができます。この場合、Camel はリバース HTTP プロキシーとして機能し、APIcast は Camel にトラフィックを送信し、Camel がそのトラフィックを API バックエンドに送信します。

トラフィックフローの例を以下に示します。

3scale バックエンドに送信された APIcast トラフィックは、すべて Camel プロキシーを使用しません。このポリシーは、Camel プロキシーおよび APIcast と API バックエンド間の通信にのみ適用されます。

すべてのトラフィックをプロキシー経由で送信するには、HTTP_PROXY 環境変数を使用する必要があります。

"policy_chain": [
    {
      "name": "apicast.policy.apicast"
    },
    {
      "name": "apicast.policy.camel",
      "configuration": {
          "all_proxy": "http://192.168.15.103:8080/",
          "http_proxy": "http://192.168.15.103:8080/",
          "https_proxy": "http://192.168.15.103:8443/"
      }
    }
]

http_proxy または https_proxy が定義されていない場合は、all_proxy の値が使用されます。

一般的な HTTP プロキシーポリシー使用の詳細は、「Proxy Service」を参照してください。

Cross Origin Resource Sharing (CORS) Request Handling ポリシーを使用すると、以下の項目を指定することができるので CORS の動作の制御が可能です。

CORS Request Handling ポリシーにより、指定されていない CORS リクエストはすべてブロックされます。

設定プロパティー

ポリシーオブジェクトの例

{
  "name": "cors",
 "version": "builtin",
 "configuration": {
   "allow_headers": [
     "App-Id", "App-Key",
     "Content-Type", "Accept"
   ],
   "allow_credentials": true,
   "allow_methods": [
     "GET", "POST"
   ],
   "allow_origin": "https://example.com",
   "max_age" : 200
  }
}

ポリシーの設定方法に関する情報は、3scale 管理ポータルでのポリシーチェーンの変更を参照してください。

Custom Metrics ポリシーにより、アップストリーム API によって送信されるレスポンスの後にメトリクスを追加することができます。このポリシーの主なユースケースは、レスポンスコードのステータス、ヘッダー、またはさまざまな NGINX 変数に基づいてメトリクスを追加する場合です。

{
  "name": "apicast.policy.custom_metrics",
  "configuration": {
    "rules": [
      {
        "metric": "error",
        "increment": "{{ resp.headers['increment'] }}",
        "condition": {
          "operations": [
            {
              "right": "{{status}}",
              "right_type": "liquid",
              "left": "400",
              "op": "=="
            }
          ],
          "combine_op": "and"
        }
      }
    ]
  }
}

このポリシーは、アップストリーム API が 200 のステータスを返すと、status_code 情報により hits メトリクスのカウントを増やします。

{
  "name": "apicast.policy.custom_metrics",
  "configuration": {
    "rules": [
      {
        "metric": "hits_{{status}}",
        "increment": "1",
        "condition": {
          "operations": [
            {
              "right": "{{status}}",
              "right_type": "liquid",
              "left": "200",
              "op": "=="
            }
          ],
          "combine_op": "and"
        }
      }
    ]
  }
}

Echo ポリシーは、受信したリクエストを出力してクライアントに返します。また、オプションで任意の HTTP ステータスコードを返します。

設定プロパティー

ポリシーオブジェクトの例

{
  "name": "echo",
  "version": "builtin",
  "configuration": {
    "status": 404,
    "exit": "request"
  }
}

ポリシーの設定方法に関する情報は、本書の3scale でのポリシーチェーンの作成セクションを参照してください。

Edge Limiting ポリシーの目的は、バックエンド API に送信されるトラフィックに対する柔軟な流量制御を提供することで、このポリシーをデフォルトの 3scale 承認メカニズムと共に使用することができます。このポリシーでサポートされるユースケースの例を以下に示します。

すべての制限をサービスごとまたはグローバルに適用することができます。

key は以下のプロパティーで定義されるオブジェクトです。

それぞれの制限は、そのタイプに応じたパラメーターも持ちます。

サービスごとにさまざまな制限を定義することができます。複数の制限を定義した場合には、少なくとも 1 つの制限に達すると、リクエストは拒否または遅延されます。

{
  "key": { "name": "{{ jwt.sub }}", "name_type": "liquid" },
  "count": 10,
  "window": 60
}

Liquid のサポートに関する詳細な情報は、「ポリシーでの変数およびフィルターの使用」を参照してください。

以下のプロパティーで condition を定義します。

"condition": {
  "combine_op": "and",
  "operations": [
    {
      "op": "==",
      "right": "GET",
      "left_type": "liquid",
      "left": "{{ http_method }}",
      "right_type": "plain"
    }
  ]
}

Header Modification ポリシーを使用すると、受信したリクエストまたはレスポンスに関して、既存のヘッダーを変更する、補足のヘッダーを定義して追加する、またはヘッダーを削除することができます。レスポンスヘッダーおよびリクエストヘッダーの両方を変更することができます。

Header Modification ポリシーでは、以下の設定パラメーターがサポートされます。

それぞれの操作は、以下のパラメーターで設定されます。

ポリシーオブジェクトの例

{
  "name": "headers",
  "version": "builtin",
  "configuration": {
    "response": [
      {
        "op": "add",
        "header": "Custom-Header",
        "value_type": "plain",
        "value": "any-value"
      }
    ],
    "request": [
      {
        "op": "set",
        "header": "Authorization",
        "value_type": "plain",
        "value": "Basic dXNlcm5hbWU6cGFzc3dvcmQ="
      },
      {
        "op": "set",
        "header": "Service-ID",
        "value_type": "liquid",
        "value": "{{service.id}}"
      }
    ]
  }
}

ポリシーの設定方法に関する情報は、本書の3scale でのポリシーチェーンの作成セクションを参照してください。

API プロバイダーは、HTTP Status Code Overwrite ポリシーを API プロダクトに追加できます。このポリシーにより、アップストリームのレスポンスコードを、指定したレスポンスコードに変更できます。3scale は、HTTP Status Code Overwrite ポリシーをアップストリームサービスから送信されたレスポンスコードに適用します。つまり、3scale が公開する API が状況に合わないコードを返す場合には、そのコードをアプリケーションに意味のあるレスポンスコードに変更するために、HTTP Status Code Overwrite ポリシーを設定することができます。

ポリシーチェーンでは、変更するレスポンスコードを生成するポリシーが HTTP Status Code Overwrite ポリシーの前にある必要があります。変更するステータスコードを生成するポリシーがない場合、HTTP Status Code Overwrite ポリシーのポリシーチェーンでの位置は重要ではありません。

管理ポータルで、HTTP Status Code Overwrite ポリシーをプロダクトのポリシーチェーンに追加します。ポリシーチェーンでポリシーをクリックし、変更するアップストリームレスポンスコードと、代わりに返したいレスポンスコードを指定します。上書きする追加のアップストリームレスポンスコードごとに正符号をクリックします。たとえば、HTTP Status Code Overwrite ポリシーを使用して、アップストリームの 201Created レスポンスコードを 200OK レスポンスコードに変更できます。

変更するレスポンスコードのもう 1 つの例は、コンテンツ制限を超える場合のレスポンスです。アップストリームが 413 payload too large を返す場合に、414 request-URI too long のレスポンスコードであれば役立ちます。

管理ポータルで HTTP Status Code Overwrite ポリシーを追加する代わりに、ポリシーチェーン設定ファイルと共に 3scale API を使用できます。

{
  "name": "statuscode_overwrite",
  "version": "builtin",
  "configuration": {
    "http_statuses": [
      {
        "upstream": 200,
        "apicast": 201
      },
      {
        "upstream": 413,
        "apicast": 414
      }
    ]
  }
}

HTTP2 エンドポイントポリシーは、リクエストを送信するコンシューマーアプリケーションと APIcast 間の HTTP/2 プロトコル接続を有効にします。HTTP2 エンドポイントポリシーがプロダクトのポリシーチェーンにある場合、API キャストにリクエストを行うコンシューマーアプリケーションからアップストリームサービスへの通信フロー全体が HTTP/2 プロトコルを使用することができます。

HTTP2 エンドポイントポリシーがポリシーチェーンにある場合:

IP Check ポリシーは、IP のリストに基づいてリクエストを拒否または許可するために使用します。

設定プロパティー

ポリシーオブジェクトの例

{
  "name": "ip_check",
  "configuration": {
    "ips": [ "3.4.5.6", "1.2.3.0/4" ],
    "check_type": "blacklist",
    "client_ip_sources": ["X-Forwarded-For", "X-Real-IP", "last_caller"],
    "error_msg": "A custom error message"
  }
}

ポリシーの設定方法に関する情報は、本書の3scale でのポリシーチェーンの作成セクションを参照してください。

JWT Claim Check ポリシーを使用すると、JSON Web Token (JWT) クレームに基づきリソースターゲットおよびメソッドをブロックする、新たなルールを定義することができます。

JWT Claim Check ポリシーがリソースおよびメソッドをブロックしている場合には、ポリシーは JWT 操作も検証します。一方、メソッドおよびリソースがマッチしない場合には、リクエストはバックエンド API に送信されます。

以下の GET リクエストの例では、JWT には管理者として role クレームが必要です。もしなければ、リクエストは拒否されます。一方、GET 以外のリクエストは JWT 操作を検証しないため、POST リソースは JWT の制約なしに許可されます。

{
  "name": "apicast.policy.jwt_claim_check",
  "configuration": {
      "error_message": "Invalid JWT check",
      "rules": [
          {
              "operations": [
                  {"op": "==", "jwt_claim": "role", "jwt_claim_type": "plain", "value": "admin"}
              ],
              "combine_op":"and",
              "methods": ["GET"],
              "resource": "/resource",
              "resource_type": "plain"
          }
      ]
  }
}

このポリシーは JSON を使用して API リクエストに応答します。コンテキストで利用可能なオブジェクトおよび値を含み、Liquid テンプレートの評価に使用することができます。3scale APIcast または Upstream ポリシーと組み合わせる場合には、正常な動作のためにポリシーチェーンではこれらのポリシーの前に Liquid Context Debug ポリシーを設定する必要があります。循環参照を避けるために、ポリシーには重複するオブジェクトは 1 回だけ含め、それをスタブ値で置き換えます。

このポリシーが有効な時に APIcast が返す値の例を以下に示します。

    {
      "jwt": {
        "azp": "972f7b4f",
        "iat": 1537538097,
        ...
        "exp": 1537574096,
        "typ": "Bearer"
      },
      "credentials": {
        "app_id": "972f7b4f"
      },
      "usage": {
        "deltas": {
          "hits": 1
        },
        "metrics": [
          "hits"
        ]
      },
      "service": {
        "id": "2",
        ...
      }
      ...
    }

Logging ポリシーには 2 つの目的があります。

Logging ポリシーとアクセスログの場所のグローバル設定を組み合わせることができます。APIcast アクセスログの場所を設定するには、APICAST_ACCESS_LOG_FILE 環境変数を設定します。デフォルトでは、この変数は標準出力デバイスの /dev/stdout に設定されています。グローバル APIcast パラメーターに関する詳細な情報は、6章APIcast の環境変数を参照してください。

また、Logging ポリシー機能に関する補足情報を以下に示します。

local cjson = require('cjson')
local PolicyChain = require('apicast.policy_chain')
local policy_chain = context.policy_chain

local logging_policy_config = cjson.decode([[
{
  "enable_access_logs": false,
  "custom_logging": "\"{{request}}\" to service {{service.id}} and {{service.name}}"
}
]])

policy_chain:insert( PolicyChain.load_policy('logging', 'builtin', logging_policy_config), 1)

return {
  policy_chain = policy_chain,
  port = { metrics = 9421 },
}

docker run --name apicast --rm -p 8080:8080 \
    -v $(pwd):/config \
    -e APICAST_ENVIRONMENT=/config/custom_env.lua \
    -e THREESCALE_PORTAL_ENDPOINT=https://ACCESS_TOKEN@ADMIN_PORTAL_DOMAIN \
    quay.io/3scale/apicast:master

{
  "name": "apicast.policy.logging",
  "configuration": {
    "enable_access_logs": false
  }
}

{
  "name": "apicast.policy.logging",
  "configuration": {
    "enable_access_logs": false,
    "custom_logging": "[{{time_local}}] {{host}}:{{server_port}} {{remote_addr}}:{{remote_port}} \"{{request}}\" {{status}} {{body_bytes_sent}} ({{request_time}}) {{post_action_impact}}",
  }
}

{
  "name": "apicast.policy.logging",
  "configuration": {
    "enable_access_logs": false,
    "custom_logging": "\"{{request}}\" to service {{service.id}} and {{service.serializable.name}}",
  }
}

{
  "name": "apicast.policy.logging",
  "configuration": {
    "enable_access_logs": false,
    "enable_json_logs": true,
    "json_object_config": [
      {
        "key": "host",
        "value": "{{host}}",
        "value_type": "liquid"
      },
      {
        "key": "time",
        "value": "{{time_local}}",
        "value_type": "liquid"
      },
      {
        "key": "custom",
        "value": "custom_method",
        "value_type": "plain"
      }
    ]
  }
}

{
  "name": "apicast.policy.logging",
  "configuration": {
    "enable_access_logs": false,
    "custom_logging": "\"{{request}}\" to service {{service.id}} and {{service.name}}",
    "condition": {
      "operations": [
        {"op": "==", "match": "{{status}}", "match_type": "liquid", "value": "200"}
      ],
      "combine_op": "and"
    }
  }
}

{
  "name": "apicast.policy.logging",
  "configuration": {
    "enable_access_logs": false,
    "custom_logging": "\"{{request}}\" to service {{service.id}} and {{service.name}}",
    "condition": {
      "operations": [
        {"op": "==", "match": "{{status}}", "match_type": "liquid", "value": "200"},
        {"op": "==", "match": "{{status}}", "match_type": "liquid", "value": "500"}
      ],
      "combine_op": "or"
    }
  }
}

Maintenance Mode ポリシーを使用すると、指定したステータスコードおよびメッセージと共に受信したリクエストを拒否することができます。このポリシーは、メンテナーンス期間または API を一時的にブロックする場合に役立ちます。

設定プロパティー

設定可能なプロパティーおよびデフォルト値を、以下のリストに示します。

{
  "policy_chain": [
    {"name": "maintenance-mode", "version": "1.0.0",
    "configuration": {"message": "Be back soon..", "status": 503} },
  ]
}

{
    "name": "maintenance_mode",
    "version": "builtin",
    "configuration": {
        "message_content_type": "text/plain; charset=utf-8",
        "message": "Echo API /test is currently Unavailable",
        "condition": {
            "combine_op": "and",
            "operations": [
                {
                    "left_type": "liquid",
                    "right_type": "plain",
                    "op": "==",
                    "left": "{{ original_request.path }}",
                    "right": "/test"
                }
            ]
        },
        "status": 503
    }
}

ポリシーの設定方法に関する情報は、本書の3scale でのポリシーチェーンの作成セクションを参照してください。

NGINX は一部のリクエストヘッダーを自動的にチェックし、これらのヘッダーを検証できない場合にリクエストを拒否します。たとえば、NGINX は NGINX が検証できない If-Match ヘッダーのあるリクエストを拒否します。NGINX が特定のヘッダーの検証を省略するようにする場合は、NGINX Filter ポリシーを追加します。

NGINX Filter ポリシーを追加する場合、NGINX が検証をスキップするリクエストヘッダーを 1 つ以上指定します。指定するヘッダーごとに、ヘッダーをリクエストに残すかどうかを指定します。たとえば、以下の JSON コードは NGINX Filter ポリシーを追加して、If-Match ヘッダーの検証をスキップするが、アップストリームサーバーに転送されるリクエストに If-Match ヘッダーを保持するように設定することができます。

{ "name": "apicast.policy.nginx_filters",
  "configuration": {
    "headers": [
      {"name": "If-Match", "append": true}
    ]
  }
}

以下の例でも If-Match ヘッダーの検証をスキップしますが、このコードは、リクエストをアップストリームサーバーに送信する前に If-Match ヘッダーを削除するように NGINX に指示します。

{ "name": "apicast.policy.nginx_filters",
  "configuration": {
    "headers": [
      {"name": "If-Match", "append": false}
    ]
  }
}

アップストリームサーバーに送信されるリクエストに指定のヘッダーを追加するかどうかに関係なく、NGINX が指定したヘッダーを検証できない場合に NGINX 412 応答コードを回避します。

このポリシーは、全 API コールに対して OAuth 2.0 相互 TLS クライアント認証を実行します。

OAuth 2.0 Mutual TLS Client Authentication ポリシーの JSON の例を以下に示します。

{
  "$schema": "http://apicast.io/policy-v1/schema#manifest#",
  "name": "OAuth 2.0 Mutual TLS Client Authentication",
  "summary": "Configure OAuth 2.0 Mutual TLS Client Authentication.",
  "description": ["This policy executes OAuth 2.0 Mutual TLS Client Authentication ",
    "(https://tools.ietf.org/html/draft-ietf-oauth-mtls-12) for every API call."
  ],
  "version": "builtin",
  "configuration": {
    "type": "object",
    "properties": { }
  }
}

OAuth 2.0 Token Introspection ポリシーを使用すると、OpenID Connect (OIDC) 認証オプションを用いるサービスに使用される JSON Web Token (JWT) トークンを検証することができます。この場合、トークン発行者 (Red Hat Single Sign-On) のトークンイントロスペクションエンドポイントを使用します。

トークンイントロスペクションエンドポイントおよびそのエンドポイントに呼び出しを行う際に APIcast が使用するクレデンシャルを定義する場合、auth_type フィールドでは以下の認証タイプがサポートされます。

auth_type フィールドの設定にかかわらず、APIcast は Basic 認証を使用してトークンイントロスペクションの呼び出しを承認します (Authorization: Basic <token> ヘッダー、ここで <token> は Base64 でエンコードされた <client_id>:<client_secret> 設定です)。

トークンイントロスペクションエンドポイントのレスポンスには、active 属性が含まれます。APIcast はこの属性の値を確認します。属性の値に応じて、APIcast は呼び出しを承認または拒否します。

このポリシーを使用すると、トークンのキャッシュを有効にして、同じ JWT トークンに対する呼び出しのたびにトークンイントロスペクションエンドポイントに呼び出しを行うのを避けることができます。Token Introspection ポリシーのトークンキャッシュを有効にするには、max_cached_tokens フィールドを 0 (機能は無効) から 10000 までの値に設定します。さらに、max_ttl_tokens フィールドで、トークンの残存期間 (TTL) の値を 1 から 3600 秒に設定することができます。

API プロバイダーは、On Fail ポリシーを API プロダクトに追加できます。On Fail ポリシーがポリシーチェーンにあり、特定の API コンシューマーリクエストに対してポリシーの実行に失敗すると、APIcast は以下の処理を行います。

On Fail ポリシーは、不適切な設定やカスタムポリシーのコンプライアンス違反のコードが原因で、APIcast がポリシーを処理できない場合に役立ちます。ポリシーチェーンに On Fail ポリシーがないと、APIcast はポリシーを適用できないポリシーをスキップし、チェーン内の他のポリシーを処理し、リクエストをアップストリーム API に送信します。ポリシーチェーンに On Fail ポリシーがあると、APIcast はリクエストを拒否します。

ポリシーチェーンでは、On Fail ポリシーを任意の場所に配置できます。

管理ポータルで、On Fail ポリシーをプロダクトのポリシーチェーンに追加します。ポリシーチェーンでポリシーをクリックし、On Fail ポリシーを適用する際に APIcast が返すステータスコードを指定します。たとえば、クライアントからの不適切なリクエストを示す 400 を指定できます。

Proxy Service ポリシーを使用して、定義したプロキシーを使用して 3scale のトラフィックを送信する一般的な HTTP プロキシー を定義することができます。この場合、プロキシーサービスはリバース HTTP プロキシーとして機能し、APIcast は HTTP プロキシーにトラフィックを送信し、プロキシーがそのトラフィックを API バックエンドに送信します。

トラフィックフローの例を以下に示します。

3scale バックエンドに送信された APIcast トラフィックは、すべてプロキシーを使用しません。このポリシーは、プロキシーおよび APIcast と API バックエンド間の通信にのみ適用されます。

すべてのトラフィックをプロキシー経由で送信するには、HTTP_PROXY 環境変数を使用する必要があります。

"policy_chain": [
    {
      "name": "apicast.policy.apicast"
    },
    {
      "name": "apicast.policy.http_proxy",
      "configuration": {
          "all_proxy": "http://192.168.15.103:8888/",
          "https_proxy": "https://192.168.15.103:8888/",
          "http_proxy": "https://192.168.15.103:8888/"
      }
    }
]

http_proxy または https_proxy が定義されていない場合は、all_proxy の値が使用されます。

アプリケーションが流量制御の設定されたアプリケーションプランにサブスクライブする際に、Rate Limit Headers ポリシーはレスポンスメッセージに RateLimit ヘッダーを追加します。これらのヘッダーは、設定されたリクエストクォータ制限、ならびに現在の時間枠での残りのリクエストクォータおよび秒数に関する有用な情報を提供します。

プロダクトのポリシーチェーンで、Rate Limit Headers ポリシーを追加する場合、3scale APIcast ポリシーの前に設定する必要があります。3scale APIcast ポリシーが Rate Limit Headers ポリシーの前にあると、Rate Limit Headers ポリシーは機能しません。

デフォルトでは、Rate Limit Headers ポリシーが設定されていない場合やアプリケーションプランに流量制御が設定されていない場合、レスポンスメッセージには流量制御に関するヘッダーがありません。

API プロバイダーは、Response/Request Content Limits ポリシーを API プロダクトに追加できます。このポリシーにより、アップストリーム API へのリクエストのサイズやアップストリーム API からのレスポンスのサイズを制限できます。このポリシーがない場合、リクエスト/レスポンスのサイズは無制限になります。

このポリシーは、以下の項目のオーバーロードを防ぐのに役立ちます。

3scale が Response/Request Content Limits ポリシーを適用するには、リクエストまたはレスポンスに content-length ヘッダーが必要です。

管理ポータルで Response/Request Content Limits ポリシーをプロダクトに追加したら、それをクリックして制限をバイト単位で指定します。リクエストの制限またはレスポンスの制限のいずれか、またはその両方を指定することができます。デフォルト値は 0 で、サイズが無制限であることを意味します。

または、以下のようにポリシーチェーン設定ファイルを更新して、このポリシーを追加することができます。

{
  "name": "apicast.policy.limits",
  "configuration":
  {
    "request": 100,
    "response": 100
  }
}

OpenID Connect 認証オプションと共に使用した場合、このポリシーによりロールの確認機能が追加されます。このポリシーは、Red Hat Single Sign-On (RH-SSO) により発行されたアクセストークンのレルムロールおよびクライアントロールを確認します。レルムロールを指定すると、3scale のすべてのクライアントリソースにロールの確認機能が追加されます。

ポリシー設定の type プロパティーで指定するロールの確認には、2 つのタイプがあります。

同じポリシーに blacklist および whitelist 両方のチェックを設定することはできませんが、APIcast ポリシーチェーンに複数の RH-SSO/Keycloak Role Check ポリシーインスタンスを追加することができます。

ポリシー設定の scopes プロパティーを使用して、スコープのリストを設定することができます。

それぞれの scope オブジェクトには、以下のプロパティーがあります。

Routing ポリシーを使用すると、リクエストをさまざまなターゲットエンドポイントにルーティングすることができます。ターゲットエンドポイントを定義すると、正規表現を使用して UI から受信したリクエストをターゲットエンドポイントにルーティングできるようになります。

Liquid Context Debug
JWT Claim Check
Routing
3scale APIcast

Liquid Context Debug
Routing
3scale APIcast
JWT Claim Check

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/accounts"
              }
            ]
          }
        }
      ]
    }
  }

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "operations": [
              {
                "match": "header",
                "header_name": "Test-Header",
                "op": "==",
                "value": "123"
              }
            ]
          }
        }
      ]
    }
  }

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "operations": [
              {
                "match": "query_arg",
                "query_arg_name": "test_query_arg",
                "op": "==",
                "value": "123"
              }
            ]
          }
        }
      ]
    }
  }

以下の設定では、JWT クレーム test_claim の値が 123 の場合に http://example.com にルーティングします。

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "operations": [
              {
                "match": "jwt_claim",
                "jwt_claim_name": "test_claim",
                "op": "==",
                "value": "123"
              }
            ]
          }
        }
      ]
    }
  }

以下の設定では、リクエストのパスが /accounts で、かつヘッダー Test-Header の値が 123 の場合に、http://example.com にルーティングします。

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "combine_op": "and",
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/accounts"
              },
              {
                "match": "header",
                "header_name": "Test-Header",
                "op": "==",
                "value": "123"
              }
            ]
          }
        }
      ]
    }
  }

以下の設定では、リクエストのパスが /accounts であるか、またはヘッダー Test-Header の値が 123 の場合に、http://example.com にルーティングします。

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "combine_op": "or",
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/accounts"
              },
              {
                "match": "header",
                "header_name": "Test-Header",
                "op": "==",
                "value": "123"
              }
            ]
          }
        }
      ]
    }
  }

複数のルールで設定される設定を以下に示します。

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://some_upstream.com",
          "condition": {
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/accounts"
              }
            ]
          }
        },
        {
          "url": "http://another_upstream.com",
          "condition": {
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/users"
              }
            ]
          }
        }
      ]
    }
  }

以下の設定では、パスが /abc の場合にはリクエストを http://some_upstream.com にルーティングし、パスが /def の場合には http://another_upstream.com にルーティングし、上記ルールのどちらも true と評価されない場合には http://default_upstream.com にルーティングします。

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://some_upstream.com",
          "condition": {
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/abc"
              }
            ]
          }
        },
        {
          "url": "http://another_upstream.com",
          "condition": {
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/def"
              }
            ]
          }
        },
        {
          "url": "http://default_upstream.com",
          "condition": {
            "operations": []
          }
        }
      ]
    }
  }

以下の設定では、!= が使用されています。パスが /accounts ではない場合に http://example.com にルーティングします。

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "operations": [
              {
                "match": "path",
                "op": "!=",
                "value": "/accounts"
              }
            ]
          }
        }
      ]
    }
  }

以下の設定では、リクエストをルーティングするのにその値が使用されています。

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "operations": [
              {
                "match": "header",
                "header_name": "Test-Header",
                "op": "==",
                "value": "{{ my_var }}",
                "value_type": "liquid"
              }
            ]
          }
        }
      ]
    }
  }

以下の設定では、Host ヘッダーのホストに some_host.com が指定されています。

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "host_header": "some_host.com",
          "condition": {
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/"
              }
            ]
          }
        }
      ]
    }
  }

SOAP ポリシーでは、ポリシーで指定したマッピングルールを使用して、HTTP リクエストの SOAPAction または Content-Type ヘッダーにより提供される SOAP アクション URI との照合を行います。

設定プロパティー

ポリシーオブジェクトの例

{
  "name": "soap",
  "version": "builtin",
  "configuration": {
    "mapping_rules": [
      {
        "pattern": "http://example.com/soap#request",
        "metric_system_name": "soap",
        "delta": 1
      }
    ]
  }
}

ポリシーの設定方法に関する情報は、このドキュメントの 3scale でのポリシーチェーンの作成 セクションを参照してください。

TLS Client Certificate Validation ポリシーでは、APIcast は TLS ハンドシェイクを実装し、ホワイトリストに対してクライアント証明書を検証します。ホワイトリストには、認証局 (CA) によって署名された証明書、または単なるクライアント証明書が含まれます。証明書の有効期限が切れている、または証明書が無効な場合には、リクエストは拒否され他のポリシーは処理されません。

クライアントは APIcast に接続してリクエストを送信し、クライアント証明書を提供します。APIcast は、ポリシー設定に従って受信したリクエストで提供された証明書の信ぴょう性を検証します。アップストリームに接続する際に独自のクライアント証明書を使用するように、APIcast を設定することもできます。

3scale システムにアクセスできること。すべてのデプロイメントが完了していること。

付加手順:

変更を保存するには、Update Policy Chain をクリックします。

プレースホルダーの [Your_user_key] に実際のキーを指定して、適用したポリシーを確認することができます。

curl https://api-3scale-apicast-staging.$WILDCARD_DOMAIN\?user_key\=[Your_user_key] -v --cacert ca/certs/ca.crt --cert ca/certs/client.crt --key ca/keys/client.key

curl https://api-3scale-apicast-staging.$WILDCARD_DOMAIN\?user_key\=[Your_user_key] -v --cacert ca/certs/ca.crt --cert ca/certs/server.crt --key ca/keys/server.key

curl https://api-3scale-apicast-staging.$WILDCARD_DOMAIN\?user_key\=[Your_user_key] -v --cacert ca/certs/ca.crt

変更を保存するには、Update Policy Chain をクリックします。

証明書の操作についての詳細は、Red Hat Certificate System のドキュメント を参照してください。

本セクションでは、Transport Layer Security (TLS) Termination ポリシーに関して、その概要、設定、検証、およびポリシーからのファイル削除について説明します。

TLS Termination ポリシーを使用すると、全 API 用の単一の証明書を使用せずにそれぞれの API ごとに TLS リクエストを終端するように、APIcast を設定することができます。APIcast は、クライアントへの接続を確立する前に設定設定をプルします。このようにして、APIcast はポリシーからの証明書を使用して TLS を終端させます。このポリシーは、以下のソースと共に機能します。

デフォルトでは、このポリシーはポリシーチェーンで有効になっていません。

以下の手順に従います。

付加手順:

変更を保存するには、Update Policy Chain をクリックします。

以下のコマンドを使用して、ポリシーが機能するかどうかをコマンドラインでテストすることができます。

curl “${public_URL}:${port}/?user_key=${user_key}" --cacert ${path_to_certificate}/ca.pem -v

ここで、

証明書を削除するには、以下の手順を実施します。

変更を保存するには、Update Policy Chain をクリックします。

Upstream ポリシーでは、正規表現を使用して Host リクエストヘッダーを解析し、プライベートベース URL で定義されたアップストリーム URL を別の URL に置き換えることができます。

例:

正規表現 /foo および URL フィールド newexample.com が設定されたポリシーが、URL https://www.example.com/foo/123/ を newexample.com に置き換える

ポリシーチェーンの参照

ポリシーオブジェクトの例

{
  "name": "upstream",
  "version": "builtin",
  "configuration": {
    "rules": [
      {
        "regex": "^/v1/.*",
        "url": "https://api-v1.example.com",

      }
    ]
  }
}

ポリシーの設定方法に関する情報は、このドキュメントの 3scale でのポリシーチェーンの作成 セクションを参照してください。

Upstream Mutual TLS ポリシーを使用すると、設定で指定した証明書に基づいて、APIcast とアップストリーム API との間で相互 TLS 接続を確立して検証することができます。

verify フィールドを有効にすると、ポリシーはアップストリーム API からのサーバー証明書も検証します。ca_certificates には、APIcast がサーバーの検証に使用する -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- を含めた Privacy Enhanced Mail (PEM) 形式の証明書が含まれます。

ポリシーチェーンで Upstream Mutual TLS を設定するには、3scale システムにアクセスできる必要があります。

変更をプロモートするには、以下の手順を実施します。

v# は、プロモートされる設定のバージョン番号を表します。

{
  "name": "apicast.policy.upstream_mtls",
  "configuration": {
      "certificate": "/secrets/client.cer",
      "certificate_type": "path",
      "certificate_key": "/secrets/client.key",
      "certificate_key_type": "path"
  }
}

{
  "name": "apicast.policy.upstream_mtls",
  "configuration": {
    "certificate_type": "embedded",
    "certificate_key_type": "embedded",
    "certificate": "data:application/pkix-cert;name=client.cer;base64,XXXXXXXXXXX",
    "certificate_key": "data:application/x-iwork-keynote-sffkey;name=client.key;base64,XXXXXXXX"
  }
}

Upstream Mutual TLS に関する追加のフィールド、ca_certificates、および verify についての詳細は、ポリシー設定スキーマ を参照してください。

URL Rewriting ポリシーを使用すると、リクエストのパスおよびクエリー文字列を変更することができます。

3scale APIcast ポリシーと組み合わせる場合には、ポリシーチェーンで URL Rewriting ポリシーを APIcast ポリシーの前に設定すると、APIcast のマッピングルールは変更したパスに適用されます。ポリシーチェーンで URL Rewriting ポリシーを APIcast ポリシーの後に設定すると、マッピングルールは元のパスに適用されます。

このポリシーでは、以下の 2 つの操作セットがサポートされます。

{
  "name": "url_rewriting",
  "version": "builtin",
  "configuration": {
    "query_args_commands": [
      {
        "op": "add",
        "arg": "addarg",
        "value_type": "plain",
        "value": "addvalue"
      },
      {
        "op": "delete",
        "arg": "user_key",
        "value_type": "plain",
        "value": "any"
      },
      {
        "op": "push",
        "arg": "pusharg",
        "value_type": "plain",
        "value": "pushvalue"
      },
      {
        "op": "set",
        "arg": "setarg",
        "value_type": "plain",
        "value": "setvalue"
      }
    ],
    "commands": [
      {
        "op": "sub",
        "regex": "^/api/v\\d+/",
        "replace": "/internal/",
        "options": "i"
      }
    ]
  }

APIcast に送信される元のリクエスト URI:

https://api.example.com/api/v1/products/123/details?user_key=abc123secret&pusharg=first&setarg=original

URL の書き換えを適用した後に APIcast が API バックエンドに送信する URI:

https://api-backend.example.com/internal/products/123/details?pusharg=first&pusharg=pushvalue&setarg=setvalue

以下の変換が適用されます。

ポリシーの設定方法に関する情報は、このドキュメントの 3scale でのポリシーチェーンの作成 セクションを参照してください。

URL Rewriting with Captures ポリシーは URL Rewriting ポリシーの代替で、API リクエストの URL を API バックエンドに渡す前に書き換えることができます。

URL Rewriting with Captures ポリシーは URL の引数を取得し、その値を書き換えられる URL で使用します。

このポリシーでは transformations 設定パラメーターがサポートされます。これは、リクエスト URL に適用される変換を定義するオブジェクトのリストです。それぞれの変換オブジェクトは、以下の 2 つのプロパティーで設定されます。

元の URL のクエリーパラメーターは、template で指定したクエリーパラメーターとマージされます。

例

URL Rewriting with Captures ポリシーは、以下のように設定します。

{
  "name": "rewrite_url_captures",
  "version": "builtin",
  "configuration": {
    "transformations": [
      {
        "match_rule": "/api/v1/products/{productId}/details",
        "template": "/internal/products/details?id={productId}&extraparam=anyvalue"
      }
    ]
  }
}

APIcast に送信される元のリクエスト URI:

https://api.example.com/api/v1/products/123/details?user_key=abc123secret

URL の書き換えを適用した後に APIcast が API バックエンドに送信する URI:

https://api-backend.example.com/internal/products/details?user_key=abc123secret&extraparam=anyvalue&id=123

Websocket ポリシーは、アップストリーム API への WebSocket プロトコル接続を有効にします。WebSocket プロトコルを有効にする予定の場合は、以下を考慮してください。

WebSocket 接続を有効にするアップストリーム API については、そのバックエンドを http[s] または ws[s] として定義できます。

Websocket ポリシーをポリシーチェーンに追加する場合は、3scale APIcast ポリシーの前に Websocket ポリシーが設定されていることを確認してください。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

カスタムポリシー 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 ポリシーをポリシーチェーンのどこに設定したかによって、ポリシーの動作が変わります。

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

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

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

カスタム APIcast ポリシーを新規に作成することや、標準ポリシーを変更することができます。

カスタムポリシーを作成するには、以下の点を理解している必要があります。

オンプレミスデプロイメントにカスタム APIcast ポリシーを追加するには、カスタムポリシーが含まれる OpenShift イメージをビルドし、それをデプロイメントに追加する必要があります。3scale では、サンプルリポジトリーを提供しています。このリポジトリーを、カスタムポリシーを作成してオンプレミスデプロイメントに追加するためのフレームワークとして使用することができます。

このサンプルリポジトリーには、カスタムポリシー用の正しいディレクトリー構造に加えて、イメージストリームを作成するテンプレート、および作成するカスタムポリシーが含まれる新しい APIcast OpenShift イメージをビルドするための BuildConfigs が含まれています。

カスタムポリシーを OpenShift Container Platform (OCP) 上の APIcast に追加することができます。そのためには、ご自分のカスタムポリシーが含まれる APIcast イメージを 統合 OpenShift Container Platform レジストリー から取得します。

外部の Lua 依存関係をカスタムポリシーに追加して、APIcast がまだ 3scale イメージにない Lua ライブラリーを使用できるようにすることができます。

以下の手順では、レスポンスボディーを JSON から XML に変換するカスタムポリシーの例 を使用して、この作業を行う方法を説明します。カスタムポリシーの例には、Lua で書かれた xml2lua XML パーサーが必要です。完全な例は、ビルドおよびテストを簡潔に示していますが、サンプル手順のみに従ってカスタムポリシーをデプロイすることはできません。外部の Lua 依存関係を持つカスタムポリシーをデプロイするには、この手順と共に 別の OpenShift Container Platform 上の 3scale へのカスタムポリシーの追加 の手順を実施する必要があります。

JSON to XML カスタムポリシーは、例としてのみ提示しています。実稼働環境で使用するためのものではありません。

apicast push_policy コマンドにより、カスタムポリシーマニフェストを管理ポータルにプッシュすることができます。

apicast push_policy <name> <version> <admin_portal_domain> <access_token>

必要な引数は以下のとおりです。

以下に例を示します。

$ bin/apicast push_policy my_custom_policy 1.0 my_account-admin.3scale.net XXXXXXXXXXXX...

カスタムポリシーが追加され APIcast が再起動されると、既存のサービスはこの新しいポリシーを利用可能なポリシーリストで認識し、任意のポリシーチェーンで使用することができます。

カスタムポリシーがイメージから削除され APIcast が再起動されると、そのポリシーはリスト上で利用可能なポリシーリストとは表示されなくなり、ポリシーチェーンに追加することができなくなります。

Prometheus UI において、Prometheus Query Language (PromQL) でクエリーを作成してメトリクス情報を抽出することができます。PromQL を使用すると、リアルタイムに時系列データを選択して集計することができます。

たとえば、以下のクエリーを使用すると、Prometheus が直近の 5 分間に記録したすべて時系列データから、メトリクス名が http_requests_total の値をすべて選択することができます。

http_requests_total[5m]

メトリックの ラベル (キー/値のペア) を指定して、クエリーの結果をさらに定義または絞り込むことができます。たとえば、以下のクエリーを使用すると、Prometheus が直近の 5 分間に記録したすべて時系列データから、メトリクス名が http_requests_total でかつ job ラベルが integration に設定されている値をすべて選択することができます。

http_requests_total{job="integration"}[5m]

クエリーの結果は、Prometheus の表示ブラウザーでグラフや表として表示したり、Prometheus HTTP API を使用して外部のシステムで処理したりすることができます。Prometheus はデータのグラフィカルビューを提供します。Prometheus メトリクスを表示するより安定したグラフィカルダッシュボードとしては、Grafana を選択するのが一般的です。

PromQL 言語を使用して、Prometheus alertmanager ツールで警告を設定することもできます。

オプションとして、OpenShift クラスターのクラスター管理者アクセス権限があれば、total_response_time_seconds、upstream_response_time_seconds、および upstream_status メトリクスを拡張して service_id および service_system_name ラベルを含めることができます。これらのメトリクスを拡張するには、以下のコマンドを使用して APICAST_EXTENDED_METRICS OpenShift 環境変数を true に設定します。

oc set env dc/apicast APICAST_EXTENDED_METRICS=true

APIcast ゲートウェイはオープンソースの Openresty プラットフォームに構築され、Nginx ゲートウェイ機能をさらに拡張するために、Lua モジュールを利用することができます。APIcast にはこれらのモジュールのサブセットが含まれ、これらを再利用してゲートウェイにカスタム機能を追加することができます。現在のゲートウェイに組み込まれているカスタム Lua ロジックを、カスタムポリシーに移行する必要があります。最新の APIcast では、既存の APIcast 動作を拡張/オーバーライドするのにポリシーを使用します。この働きの詳細については、ポリシー に関するドキュメントを参照してください。

一部のユースケースは考慮されていない場合があるため、Nginx 設定ファイルをカスタマイズして現在のインテグレーションの動作を維持しなければならない場合があります。そのようなケースの例を以下に示します。

設定を行う API サービスに移動します (API という名称のサービスが 1 つしかない場合には、それを選択します)。Integration セクションに移動します。

運用するサービスごとに異なる認証パターンを使用できますが、1 つのサービスに使用することのできるパターンは 1 つだけです。

認証モードを選択するには、AUTHENTICATION セクションまでスクロールします。ここで、以下のオプションのいずれかを選択することができます。

選択したクレデンシャルのタイプごとに、API の呼び出しで異なるパラメーター (キーフィールド、ID 等) を受け入れなければならない場合があります。これらのパラメーターの名前は、3scale 内部で使用されているものとは異なる場合があります。3scale バックエンドへの呼び出しで正しいパラメーター名が使用されている場合に、3scale の認証は正しく機能します。

クレデンシャルセットが機能していることを確認するには、新しいアプリケーションを作成して API を使用するためのクレデンシャルを発行します。管理ポータル Dashboard の Accounts 領域に移動し、使用するアカウントをクリックして new application をクリックします。

フォームに入力して save をクリックすると、API を使用するためのクレデンシャルと共に新しいアプリケーションが作成されます。これで、これらのクレデンシャルを使用して API を呼び出すことができ、3scale に登録されたアプリケーションのリストに対して記録が照合されます。

サポートされるクレデンシャルの中で最もシンプルな形態は、単一の API モデルです。API へのアクセス権限を持つアプリケーションは、それぞれ 1 つの (一意の) 長い文字列を持ちます。以下に例を示します。

API-key = 853a76f7c8d5f4a1ee8bf10a4e0d1f13

デフォルトでは、キーパラメーターの名前は user_key です。このラベルを使用するか、API-key 等の別のラベルを選択することができます。別のラベルを選択する場合には、3scale への承認呼び出しを行う前に値をマッピングする必要があります。この文字列は、API を使用するための識別子およびシークレットトークンの両方として機能します。このパターンは、セキュリティーに対する要件が低い環境または API の呼び出しに SSL セキュリティーが使用される環境でのみ使用することを推奨します。トークンおよびアプリケーションに対して実行される操作は、以下のとおりです。

最後のアクションのトリガーとなるのは、管理ポータルでの API 管理および API の開発者ユーザーのコンソール (許可される場合) です。

API キーの認証パターンでは、アプリケーションの識別子とシークレットトークンが 1 つのトークンに組み合わされます。一方、この認証パターンでは両者が分離されます。

app_id = 80a4e03 app_key = a1ee8bf10a4e0d1f13853a76f7c8d5f4

デフォルトの設定では、開発者はアプリケーションごとに最大 5 つのキーを作成することができます。これにより、開発者は新しいキーを作成してコードに追加し、アプリケーションを再デプロイして古いキーを無効にすることができます。そのため、API キーを再生成する場合のようなアプリケーションのダウンタイムが発生することはありません。

統計値および流量制御は、API キーごとではなく、常にアプリケーション ID レベルで維持されます。開発者が 2 組の統計値を追跡するためには、2 つのキーではなく 2 つのアプリケーションを作成する必要があります。

システムのモードを変更し、アプリケーションキーを持たないアプリケーションを作成することもできます。この場合には、3scale システムは App_ID のみに基づいてアクセスを認証します (キーの確認は行われません)。このモードは、ウィジェットタイプのシナリオ、またはアプリケーションではなくユーザーに流量制御が適用される場合に役立ちます。ほとんどの API では、アプリケーションごとに少なくとも 1 つのアプリケーションキーを持つ必要があります。この設定は、[your_API_name] > Integration > Settings で可能です。

OpenID Connect による認証に関する詳細は、OpenID Connect インテグレーションの章を参照してください。

信頼できる認証局 (CA) が発行する証明書を RH-SSO が使用する場合には、この作業は必要ありません。ただし、信頼できる CA が発行する証明書を RH-SSO が 使用しない 場合は、3scale Zync を設定して 3scale クライアントを使用するように RH-SSO を、RH-SSO と連携するように 3scale を設定する必要があります。

OpenShift RH-SSO ダッシュボードで、RH-SSO を 3scale クライアントを使用するように設定します。これは特殊な管理クライアントです。API コンシューマーが開発者ポータルの API をサブスクライブするたびに、3scale はこの手順で作成した RH-SSO 管理クライアントを使用して API コンシューマーアプリケーションのクライアントを作成します。

3scale 管理ポータルでインテグレーション設定を指定して、RH-SSO と連携するように 3scale を設定します。