Red Hat Summit Red Hat Summitサポートコンソール開発者トライアルの開始お問い合わせ

API ゲートウェイの管理

Red Hat 3scale API Management 2.5

3scale インストール環境のより詳細な設定方法

概要

本ガイドでは、基本インストールの後に実施する設定タスクについて説明します。

前書き
リンクのコピー

本ガイドは、3scale インストール環境により詳細な設定を適用するのに役立ちます。インストールに関する基本的な情報は、3scale のインストールを参照してください。

第1章 APIcast の運用
リンクのコピー

本セクションでは、高度な APIcast 設定を使用する際に考慮すべき概念について説明します。

1.1. マッピングルール
リンクのコピー

マッピングルールにより、API に対するリクエストに応じて報告するメトリクスまたはメソッドを定義します。マッピングルールの例を以下に示します。

Mapping Rules
View larger image
Mapping Rules

このルールは、/ で始まるすべての GET リクエストがメトリクス hits のカウントを 1 つ増やす、という意味です。このルールは API に対するすべてのリクエストにマッチします。ただし、このルールは一般的すぎるので、通常は変更されます。

より具体的な Echo API ルールの例を以下に示します。

Hello World Mapping Rules
View larger image
Hello World Mapping Rules

1.1.1. マッピングルールの照合
リンクのコピー

マッピングルールは前方一致で照合され、複雑な設定が可能です (表記法は OpenAPI および ActiveDocs の仕様に準じます)。

  • マッピングルールは、スラッシュ (/) で始める必要があります。
  • 文字列 (例: /hello) を使用してパスの照合を行うことができます。

  • マッピングルールでは、クエリー文字列またはボディーにパラメーターを含めることができます (例: /{word}?value={value})。APIcast は以下のようにパラメーターを取得します。

    • GET メソッド: クエリー文字列から。
    • POST、DELETE、または PUT メソッド: ボディーから。
  • マッピングルールには名前付きワイルドカードを含めることができます (例: /{word})。このルールは、プレースホルダー {word} で定義する任意の文字にマッチします。たとえば、/morning のようなリクエストがルールにマッチします。ワイルドカードは、スラッシュとスラッシュの間またはスラッシュとピリオドの間に使用することができます。パラメーターにもワイルドカードを含めることができます。
  • デフォルトでは、指定したソート法に従ってすべてのマッピングルールが順番に評価されます。ルール /v1 を追加した場合には、パスが /v1 で始まるリクエストにマッチします (例: /v1/word または /v1/sentence)。
  • パターンの最後にドル記号 ($) を追加して、完全一致を指定することができます。たとえば、/v1/word$ は、/v1/word のリクエストにだけマッチし、/v1/word/hello のリクエストにはマッチしません。完全一致を指定する場合には、すべてにマッチするデフォルトのマッピングルール (/) を必ず無効にする必要があります。
  • 複数のマッピングルールがリクエストのパスにマッチする場合がありますが、マッチするルールがなければ、リクエストは無視され HTTP 404 ステータスコードが返されます。

1.1.2. マッピングルールのワークフロー
リンクのコピー

マッピングルールに関するワークフローを以下に示します。

  • 新たなマッピングルールを定義することができます (マッピングルールの追加 を参照)。
  • 誤って変更されないように、次回のリロード時にマッピングルールはグレーアウト表示されます。
  • 既存のマッピングルールを編集するには、右側にある鉛筆アイコンをクリックして、まずそのルールを有効にする必要があります。
  • ルールを削除するには、ゴミ箱アイコンをクリックします。
  • Update & Test Staging Configuration をクリックすると、すべての変更および削除が保存されます。

マッピングルールの追加

新たなマッピングルールを追加するには、以下の手順を実施します。

  1. Add Mapping Rule をクリックします。

  2. 以下の設定を指定します。

    • Verb: HTTP リクエストの動詞 (GET、POST、DELETE、または PUT)。
    • Pattern: 照合するパターン (例: /hello)。
    • +: メトリクスのカウントを増やす数 (例: 1)。
    • Metric (or method): メトリクスまたはメソッドの名前 (例: gethello)。
  3. Update & Test Staging Configuration をクリックして変更を適用します。

他のマッピングルールの停止

他のマッピングルールの処理を停止するには、Last? を選択します。たとえば、API Integration Settings で以下のマッピングルールを定義し、それぞれのルールに異なるメトリクスが関連付けられている場合には、 

(get) /path/to/example/search
(get) /path/to/example/{id}
Copy to Clipboard Toggle word wrap

(get) /path/to/example/search の呼び出しを行う場合、APIcast は残りのマッピングルールを処理してルールがマッチした際にそのメトリクスのカウントを増やすのを停止します。

マッピングルールの並べ替え

マッピングルールを並べ替えるには、各マッピングルールの Last? 設定の横にある緑色の矢印を使用して、ルールをドラッグアンドドロップします。Update & test in Staging Environment をクリックすると、指定した並べ替えがデータベースに保存されプロキシー設定に維持されます。

その他の設定オプションは、高度な APIcast 設定 を参照してください。

1.2. Host ヘッダー
リンクのコピー

このオプションは、Host ヘッダーが指定した値にマッチしない限りトラフィックを拒否する API バックエンドにのみ必要です。このような場合には、Host がゲートウェイの 1 つなので、ゲートウェイが API バックエンドの前にあると問題が生じます (例: xxx-yyy.staging.apicast.io)。

この問題を避けるには、AUTHENTICATION SETTINGS の Host Header フィールドで API バックエンドが想定するホストを定義します。これにより、Hosted APIcast インスタンスはホストを書き換えます。

Host Rewrite
View larger image
Host Rewrite

1.3. 実稼働環境用のデプロイメント
リンクのコピー

API インテグレーションを設定しステージング環境で動作することを確認したら、実稼働環境用 APIcast デプロイメントのいずれかに進むことができます。

Integration ページの最後に Production セクションがあります。ここに、2 つのフィールド Private Base URL (Staging セクションで設定したものと同じ) および Public Base URL があります。

1.4. 公開ベース URL
リンクのコピー

公開ベース URL は、3scale により保護されたご自分の API に開発者がリクエストを行うのに使用する URL です。これは、ご自分の APIcast インスタンスの URL になります。

Self-managed デプロイメントオプションのいずれかを使用している場合には、それぞれの環境 (ステージングおよび実稼働環境) について、ご自分の管理するドメインに属する専用の公開ベース URL を選択することができます。この URL はご自分の API バックエンドの URL とは別で、たとえば https://api.yourdomain.com:443 のようになります。ここで、yourdomain.com はご自分のドメインです。公開ベース URL を設定したら必ず変更を保存し、必要に応じてステージング環境の変更を実稼働環境にプロモートしてください。

APIcast は Public Base URL で指定したホスト名に対する呼び出ししか受け付けない点に注意してください。たとえば、上記で使用した Echo API の例で、パブリックベース URL として https://echo-api.3scale.net:443 を指定すると、正しい呼び出しは次のようになります。 

curl "https://echo-api.3scale.net:443/hello?user_key=YOUR_USER_KEY"
Copy to Clipboard Toggle word wrap

まだ API 用の公開ドメインがない場合には、リクエストに APIcast IP を使用することもできますが、それでも Public Base URL フィールドには値を指定する必要があります (実際のドメインではなくても)。その場合には Host ヘッダーでホストを指定する必要があります。以下に例を示します。 

curl "http://192.0.2.12:80/hello?user_key=YOUR_USER_KEY" -H "Host: echo-api.3scale.net"
Copy to Clipboard Toggle word wrap

ローカルマシンにデプロイしている場合には、ドメインに localhost を使用することもできます。この場合には公開ベース URL は http://localhost:80 のようになり、以下のようにリクエストを行うことができます。 

curl "http://localhost:80/hello?user_key=YOUR_USER_KEY"
Copy to Clipboard Toggle word wrap

API サービスが複数ある場合には、それぞれのサービスについてこの公開ベース URL を適切に設定する必要があります。APIcast はホスト名に基づきリクエストをルーティングします。

1.5. API バックエンドの保護
リンクのコピー

APIcast が実稼動環境で動作するようになったら、クレデンシャルが提供されない API バックエンドへの直接アクセスを制限することが望まれる場合があります。そのための最も簡単な方法は、APIcast が設定するシークレットトークンを使用することです。シークレットトークンの設定方法については、高度な APIcast 設定 を参照してください。

1.6. プライベート API を扱う APIcast の使用
リンクのコピー

APIcast を使用して、インターネット上に公開されていない API を保護することができます。そのための条件は以下のとおりです。

  • デプロイメントオプションとして、Self-managed APIcast を使用している。
  • 一般のインターネットから APIcast へのアクセスが可能で、APIcast が 3scale Service Management API に発信の呼び出しを行うことができる。
  • APIcast が API バックエンドにアクセスすることができる。

この場合には、Private Base URL フィールドに API の内部ドメイン名または IP アドレスを設定し、他の手順は通常どおりに実施することができます。ただし、ステージング環境のメリットが得られない点およびテストコールが成功しない点に注意して下さい。ステージング用 APIcast インスタンスは 3scale がホストし、プライベート API のバックエンドにはアクセスすることができないためです。しかし、APIcast を実稼働環境にデプロイして正しく設定すれば、APIcast は想定どおりに機能します。

1.7. APIcast への OpenTracing の設定
リンクのコピー

OpenTracing は API の仕様でマイクロサービスのプロファイリングおよびモニターリングに使用されるメソッドです。バージョン 3.3 以降の APIcast には、OpenTracing ライブラリーおよび Jaeger Tracer ライブラリー が含まれています。

1.7.1. 前提条件
リンクのコピー

APIcast デプロイメントに分散トレーシング機能を追加するには、以下の前提条件が満たされている必要があります。

  • それぞれの外部リクエストに、固有のリクエスト ID がアタッチされている (通常は HTTP ヘッダー経由)。
  • それぞれのサービスがリクエスト ID を他のサービスに転送する。
  • それぞれのサービスがリクエスト ID をログに出力する。
  • それぞれのサービスがリクエストの開始/終了時刻等の補足情報を記録する。
  • ログが集約され、HTTP リクエスト ID を使用して解析する手段を提供する。

1.7.2. 手順
リンクのコピー

OpenTracing を設定するには、以下の環境変数を使用します。

  • OPENTRACING_TRACER: 使用するトレーサーの実装を定義します。現在、利用することができるのは Jaeger だけです。
  • OPENTRACING_CONFIG: 使用するトレーサーのデフォルト設定ファイルを指定します。ここ に例を示します。
  • OPENTRACING_HEADER_FORWARD: オプション。実際の OpenTracing 設定に応じて、この環境変数を設定することができます。

これらの変数に関する詳細は、APIcast の環境変数 を参照してください。

インテグレーションが適切に機能しているかどうかをテストするには、トレースが Jaeger トレースインターフェイスで報告されるかどうかを確認する必要があります。

1.7.3. 補足情報
リンクのコピー

OpenTracing および Jaeger インテグレーションは、アップストリームプロジェクト (https://github.com/3scale/apicast) で公開されています。

1.7.4. OpenShift インスタンスへの Jaeger のインストール
リンクのコピー

本セクションでは、実行中の OpenShift インスタンスへの Jaeger のインストールについて説明します。

警告

Jaeger はサードパーティーコンポーネントであり、APIcast と共に使用する場合を除き 3scale はサポートを提供しません。以下の手順は参考例としてのみ提供され、実稼働環境での使用には適しません。

  1. 現在の namespace に Jaeger オールインワンをインストールします。 

    oc process -f https://raw.githubusercontent.com/jaegertracing/jaeger-openshift/master/all-in-one/jaeger-all-in-one-template.yml | oc create -f -
    Copy to Clipboard Toggle word wrap

  2. 以下の内容で Jaeger 設定ファイル jaeger_config.json を作成します。 

    {
    "service_name": "apicast",
    "disabled": false,
    "sampler": {
      "type": "const",
      "param": 1
    },
    "reporter": {
      "queueSize": 100,
      "bufferFlushInterval": 10,
      "logSpans": false,
      "localAgentHostPort": "jaeger-agent:6831"
    },
    "headers": {
      "jaegerDebugHeader": "debug-id",
      "jaegerBaggageHeader": "baggage",
      "TraceContextHeaderName": "uber-trace-id",
      "traceBaggageHeaderPrefix": "testctx-"
    },
    "baggage_restrictions": {
        "denyBaggageOnInitializationFailure": false,
        "hostPort": "127.0.0.1:5778",
        "refreshInterval": 60
    }
 }
    Copy to Clipboard Toggle word wrap
    • すべてのリクエストをサンプリングするために、sampler 定数を 1 に設定します。
    • reporter の場所およびキューサイズを設定します。
    • リクエストを追跡するのに使用する TraceContextHeaderName を含め、headers を設定します。

  3. Jaeger 設定ファイルから ConfigMap を作成し、それを APIcast にマウントします。 

    oc create configmap jaeger-config --from-file=jaeger_config.json
oc volume dc/apicast --add -m /tmp/jaeger/ --configmap-name jaeger-config
    Copy to Clipboard Toggle word wrap

  4. 前のステップで追加した設定で、OpenTracing および Jaeger を有効にします。 

    oc set env deploymentConfig/apicast OPENTRACING_TRACER=jaeger OPENTRACING_CONFIG=/tmp/jaeger/jaeger_config.json
    Copy to Clipboard Toggle word wrap

  5. Jaeger インターフェイスが動作している URL を確認します。 

    oc get route
(…) jaeger-query-myproject.127.0.0.1.nip.io
    Copy to Clipboard Toggle word wrap
  6. 前のステップで確認した URL から Jaeger インターフェイスを開きます。Openshift のヘルスチェックから読み込まれているデータが表示されます。
  7. 最後のステップは、リクエストのトレースをすべて表示できるように、OpenTracing および Jaeger のサポートをバックエンド API に追加することです。この操作は、使用されるフレームワークおよび言語に応じてバックエンドごとに異なります。例として Using OpenTracing with Jaeger to collect Application Metrics in Kubernetes を参照してください。

Jaeger の設定に関する詳細は、以下のドキュメントを参照してください。

第2章 Docker コンテナー環境の操作
リンクのコピー

2.1. Docker コンテナー環境上の APIcast に関するトラブルシューティング
リンクのコピー

本セクションでは、Docker コンテナー環境上で APIcast を使用する際に直面する、もっとも典型的な問題について説明します。

2.1.1. Cannot connect to the Docker daemon エラー
リンクのコピー

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 ユーザーとして実行してください。詳細については、このドキュメント を参照してください。

2.1.2. 基本的な Docker コマンドラインインターフェイスコマンド
リンクのコピー

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

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

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

第3章 高度な APIcast 設定
リンクのコピー

本セクションでは、ステージング環境における 3scale の API ゲートウェイの高度な設定オプションについて説明します。

3.1. シークレットトークンの定義
リンクのコピー

セキュリティー上の理由から、3scale ゲートウェイから API バックエンドに送信されるすべてのリクエストには、X-3scale-proxy-secret-token というヘッダーが含まれます。Integration ページの AUTHENTICATION SETTINGS で、このヘッダーの値を設定することができます。

Proxy secret token
View larger image
Proxy secret token

設定したシークレットトークンは、プロキシーと API 間の共有シークレットとして機能し、ゲートウェイから送信されていない API リクエストを拒否したい場合には、すべてブロックすることができます。これにより、サンドボックスゲートウェイを使用してトラフィック管理ポリシーをセットアップする際に、公開エンドポイントを保護するための新たなセキュリティーレイヤーを追加することができます。

ゲートウェイが機能するためには、API バックエンドには公開されている解決可能なドメインが必要です。したがって、API バックエンドを知っていれば、誰でもクレデンシャルの確認を迂回することができます。ステージング環境の API ゲートウェイは実稼働環境での使用を想定していないので、このことが問題になることはありません。ただし、アクセスを防げるようにしておいた方が望ましいと言えます。

3.2. クレデンシャル
リンクのコピー

3scale における API クレデンシャルは、user_key または app_id/app_key のどちらかです (使用する認証モードによります)。ステージング環境の API ゲートウェイでは OpenID Connect が有効です。ただし、Integration ページでテストすることはできません。

なお、API で異なるクレデンシャル名を使用することが望ましい場合もあります。この場合、API キーモードを使用していれば user_key にカスタムな名前を設定する必要があります。

Custom user_key
View larger image
Custom user_key

あるいは、以下のように app_id および app_key を設定します。

Custom app_key/app_id
View larger image
Custom app_key/app_id

たとえば、app_id を key に変えることが API にとってより適切であれば、名前を変更することができます。ゲートウェイは名前 key を取得し、3scale バックエンドに対して承認呼び出しを行う前に app_id に変換します。新しいクレデンシャル名には、英数字を使用しなければならない点に注意してください。

API がクレデンシャルを渡す際に、クエリー文字列 (GET 以外ではボディー) またはヘッダーのどちらを使用するかを定義することができます。

Proxy Credentials Location
View larger image
Proxy Credentials Location
注記

クレデンシャルを抽出する際に、APIcast はヘッダー名を正規化します。つまり、大文字と小文字の区別をなくし、アンダースコアとハイフンを等価に扱います。たとえば、アプリケーションキーのパラメーターを App_Key と設定した場合には、app-key 等の他の値も有効なアプリケーションキーヘッダーとして受け入れられます。

3.3. エラーメッセージ
リンクのコピー

本格的な設定のもう 1 つの重要な要素は、独自のカスタムエラーメッセージを定義することです。

ステージング環境の 3scale API ゲートウェイは、API によって生成されたすべてのエラーメッセージをパスすることに注意することが重要です。ただし、API の管理レイヤーがゲートウェイによって実行されるようになったため、一部のリクエストはゲートウェイによって終了されるため、API で表示されないエラーがいくつかあります。

カスタムエラーメッセージ
View larger image
カスタムエラーメッセージ

エラーの一部を次に示します。

  • Authentication missing: API リクエストにクレデンシャルが含まれていない場合には、必ずこのエラーが生成されます。ユーザーが API リクエストにクレデンシャルを追加しなかった場合に起こります。
  • 認証に失敗しました: このエラーは、API リクエストに有効な資格情報が含まれていない場合に生成されます。資格情報が偽物であるか、アプリケーションが一時的に中断されていることが原因である可能性があります。
  • No match: このエラーは、リクエストがどのマッピングルールにもマッチしなかったため、メトリクスが更新されないことを意味します。この状況は必ずしもエラーとは限りませんが、ユーザーが無効なパスを試みているか、マッピングルールが正当なケースに対応していないかのいずれかを意味します。
  • 再試行後: このエラーは、API リクエストがレート制限を超えるとトリガーされます。Retry-After ヘッダーが返され、ステータスコード 429 と制限が切れるまでの秒数が示されます。

3.4. 設定履歴
リンクのコピー

Update & test in Staging Environment ボタンをクリックするたびに、その時点での設定が JSON ファイルに保存されます。ステージング環境のゲートウェイは、新規リクエストのたびに最新の設定を取得します。それぞれの環境 (ステージングまたは実稼働環境) について、それまでの設定ファイルの履歴をすべて確認することができます。

以前のバージョンに自動的にロールバックすることはできない点に注意してください。その代わりに、すべての設定バージョンの履歴が、対応する JSON ファイルにより提供されます。これらのファイルを使用して、それぞれの時点でデプロイした設定を確認することができます。必要であれば、どのデプロイメントでも手動で作成し直すことができます。

3.5. デバッグ
リンクのコピー

ゲートウェイ設定のセットアップは簡単ですが、それでもエラーが発生する可能性があります。そのような状況のために、ゲートウェイはエラーを追跡するのに有用なデバッグ情報を返すことができます。

APIcast からデバッグ情報を取得するには、アクセスする API サービスに対応するサービストークンを指定して、ヘッダー X-3scale-debug: {SERVICE_TOKEN} を API リクエストに追加する必要があります。

ヘッダーが検出されサービストークンが有効であれば、ゲートウェイはレスポンスヘッダーに以下の情報を追加します。 

X-3scale-matched-rules: /v1/word/{word}.json, /v1
X-3scale-credentials: app_key=APP_KEY&app_id=APP_ID
X-3scale-usage: usage%5Bversion_1%5D=1&usage%5Bword%5D=1
Copy to Clipboard Toggle word wrap

X-3scale-matched-rules には、リクエストにマッチしているマッピングルールのコンマ区切りリストが表示されます。

ヘッダー X-3scale-credentials は、3scale バックエンドに渡されたクレデンシャルを返します。

X-3scale-usage には、3scale バックエンドに報告された使用状況が表示されます。usage%5Bversion_1%5D=1&usage%5Bword%5D=1 は usage[version_1]=1&usage[word]=1 を URL エンコードしたもので、API リクエストによりメソッド (メトリクス) version_1 および word のカウントがそれぞれ 1 増えたこと意味します。

3.6. パスルーティング
リンクのコピー

APIcast は、3scale アカウント (または APICAST_SERVICES_LIST 環境変数が設定されている場合にはサービスのサブセット) で設定されているすべての API サービスを処理します。通常、APIcast はリクエストのホスト名に基づいて API リクエストを適切な API サービスにルーティングします。そのために、公開ベース URL との照合を行います。最初にマッチしたサービスが承認に使用されます。

パスルーティング機能により、複数のサービスで同じ 公開ベース URL を使用することができ、リクエストはリクエストのパスによりルーティングされます。この機能を有効にするには、APICAST_PATH_ROUTING 環境変数を true または 1 に設定します。有効にすると、APIcast はホスト名とパスの両方に基づいて受信したリクエストをサービスにマッピングします。

同じ 公開ベース URL を使用して 1 つのゲートウェイを通じて異なるドメインでホストされる複数のバックエンドサービスを公開する場合に、この機能を使用することができます。そのためには、API バックエンド (つまり プライベートベース URL) ごとに複数の API サービスを設定し、パスルーティング機能を有効にします。

たとえば、3 つのサービスが以下のように設定されている場合、

  • サービス A 公開ベース URL: api.example.com マッピングルール: /a
  • サービス B 公開ベース URL: api2.example.com マッピングルール: /b
  • サービス C 公開ベース URL: api.example.com マッピングルール: /c

パスルーティングが 無効 な場合には (APICAST_PATH_ROUTING=false)、api.example.com に対するすべての呼び出しはサービス A との照合を試みます。したがって、呼び出し api.example.com/c および api.example.com/b はNo Mapping Rule matchedエラーと共に失敗します。

パスルーティングが 有効 な場合には (APICAST_PATH_ROUTING=true)、呼び出しはホストおよびパスの両方に照合されます。したがって、

  • api.example.com/a はサービス A にルーティングされます。
  • api.example.com/c はサービス C にルーティングされます。
  • api.example.com/b は No Mapping Rule matched エラーと共に失敗します。つまり、公開ベース URL がマッチしないので、サービス B とはマッチしません。

パスルーティングを使用する場合には、同じ 公開ベース URL を使用する複数のサービスにおいて、マッピングルールが競合しないようにする必要があります。つまり、メソッドとパスパターンの組み合わせは、それぞれ 1 つのサービスでしか使用することはできません。

第4章 APIcast ポリシー
リンクのコピー

APIcast ポリシーとは、APIcast の動作を変更する機能の単位です。ポリシーを有効、無効、および設定して、APIcast 動作の変更を制御することができます。ポリシーを使用して、デフォルトの APIcast デプロイメントでは利用することのできない機能を追加します。自分専用のポリシーを作成することや、Red Hat 3scale の提供する 標準ポリシー を使用することができます。

以下のトピックでは、標準 APIcast ポリシー、専用のカスタム APIcast ポリシーの作成、およびポリシーチェーンの作成について説明します。

ポリシーチェーンを使用して、サービスに対するポリシーを制御します。ポリシーチェーンの機能を以下に示します。

  • APIcast が使用するポリシーを指定する
  • 3scale が使用するポリシーの設定情報を提供する
  • 3scale がポリシーを読み込む順番を指定する
注記

Red Hat 3scale でカスタムポリシーを追加することは可能ですが、そのカスタムポリシーはサポートの対象ではありません。

カスタムポリシーを使用して APIIcast の動作を変更するには、以下の操作が必要です。

  • カスタムポリシーを APIcast に追加する
  • APIcast ポリシーを設定するポリシーチェーンを定義する
  • ポリシーチェーンを APIcast に追加する

4.1. APIcast 標準ポリシー
リンクのコピー

3scale では、以下の標準ポリシーが利用可能です。

3scale API Management で標準ポリシーを 有効化および設定 することができます。

4.1.1. 3scale Auth Caching ポリシー
リンクのコピー

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

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

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

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

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

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

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

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

重要

allow モードで運用した場合には、セキュリティーの低下が懸念されます。これらの懸念に念頭に置き、注意した上で allow モードを使用してください。

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

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

設定プロパティー

Expand
プロパティー説明値必須/任意

caching_type

caching_type プロパティーにより、キャッシュの動作モードを定義することができます。

データタイプ: 列挙文字列 [resilient, strict, allow, none]

必須

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

{
  "name": "caching",
  "version": "builtin",
  "configuration": {
    "caching_type": "allow"
  }
}
Copy to Clipboard Toggle word wrap

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

4.1.2. 3scale Batcher ポリシー
リンクのコピー

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

3scale Batcher ポリシーを使用すると、3scale バックエンドへのリクエスト数が大幅に削減され、レイテンシーが減少しスループットが向上します。そのために、このポリシーは承認ステータスをキャッシュし、使用状況レポートをバッチ処理します。

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

  1. それぞれのリクエストにおいて、ポリシーはクレデンシャルがキャッシュされているかどうかを確認します。

    • クレデンシャルがキャッシュされている場合には、ポリシーは 3scale バックエンドに呼び出しを行う代わりに、キャッシュされた承認ステータスを使用します。
    • クレデンシャルがキャッシュされていない場合には、ポリシーはバックエンドに呼び出しを行い、残存期間 (TTL) を設定して承認ステータスをキャッシュします。
  2. リクエストに対応する使用状況を直ちに 3scale バックエンドに報告する代わりに、ポリシーは使用状況のカウンターを累積して、バックエンドにバッチで報告します。累積した使用状況のカウンターは、独立したスレッドにより 1 回の呼び出しで 3scale バックエンドに報告されます (報告の頻度は設定が可能です)。

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

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

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

  • auths_ttl: 承認キャッシュの有効期限が切れる TTL を秒単位で設定します。

    現在の呼び出しの承認がキャッシュされている場合には、APIcast はキャッシュされた値を使用します。auths_ttl パラメーターで設定した時間が経過すると、APIcast はキャッシュを削除し、3scale バックエンドに呼び出しを行い承認のステータスを取得します。

  • batch_report_seconds: APIcast が 3scale バックエンドにバッチレポートを送信する頻度を設定します。デフォルト値は 10 秒です。
重要

このポリシーを使用するには、ポリシーチェーンで 3scale APIcast および 3scale Batcher ポリシーの両方を有効にします。

4.1.3. Anonymous Access ポリシー
リンクのコピー

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

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

注記

APIcast ポリシーおよび Anonymous Access ポリシーをポリシーチェーンで併用する場合には、APIcast ポリシーの前に Anonymous Access ポリシーを設定する必要があります。

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

  • auth_type: 以下に示す選択肢のいずれかの値を選択し、プロパティーが API に設定された認証オプションに対応している状態にします。

    • app_id_and_app_key: アプリケーション ID/アプリケーションキーによる認証オプション用
    • user_key: API キーによる認証オプション用
  • app_id (app_id_and_app_key 認証タイプにのみ有効): API の呼び出しにクレデンシャルが提供されていない場合に、承認に使用するアプリケーションのアプリケーション ID。
  • app_key (app_id_and_app_key 認証タイプにのみ有効): API の呼び出しにクレデンシャルが提供されていない場合に、承認に使用するアプリケーションのアプリケーションキー。
  • user_key (user_key 認証タイプにのみ有効): API の呼び出しにクレデンシャルが提供されていない場合に、承認に使用するアプリケーションの API キー。

図4.1 Anonymous Access ポリシー

Anonymous Access Policy
View larger image
Anonymous Access Policy

4.1.4. CORS Request Handling ポリシー
リンクのコピー

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

  • 許可されるヘッダー
  • 許可されるメソッド
  • Allow credentials
  • 許可されるオリジンヘッダー

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

注記

APIcast ポリシーおよび CORS Request Handling ポリシーをポリシーチェーンで併用する場合には、APIcast ポリシーの前に CORS Request Handling ポリシーを設定する必要があります。

設定プロパティー

Expand
プロパティー説明値必須/任意

allow_headers

allow_headers プロパティーでは、APIcast が許可する CORS ヘッダーを配列として指定することができます。

データタイプ: 文字列の配列 (CORS ヘッダーでなければなりません)

任意

allow_methods

allow_methods プロパティーでは、APIcast が許可する CORS メソッドを配列として指定することができます。

データタイプ: 列挙文字列の配列 [GET, HEAD, POST, PUT, DELETE, PATCH, OPTIONS, TRACE, CONNECT]

任意

allow_origin

allow_origin プロパティーでは、APIcast が許可するオリジンのドメインを指定することができます。

データタイプ: 文字列

任意

allow_credentials

allow_credentials プロパティーでは、APIcast がクレデンシャルの設定された 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"
  }
}
Copy to Clipboard Toggle word wrap

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

4.1.5. Echo ポリシー
リンクのコピー

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

設定プロパティー

Expand
プロパティー説明値必須/任意

status

Echo ポリシーがクライアントに返す HTTP ステータスコード

データタイプ: 整数

任意

exit

Echo ポリシーが使用する終了モードを指定します。request 終了モードは、受信したリクエストの処理を停止します。set 終了モードは書き換えフェーズを省略します。

データタイプ: 列挙文字列 [request, set]

必須

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

{
  "name": "echo",
  "version": "builtin",
  "configuration": {
    "status": 404,
    "exit": "request"
  }
}
Copy to Clipboard Toggle word wrap

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

4.1.6. Edge Limiting ポリシー
リンクのコピー

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

  • エンドユーザーの流量制御: リクエストの認証ヘッダーで渡される JWT トークンの sub(subject) クレームの値による流量制御 ({{ jwt.sub }} として設定します)。
  • 1 秒あたりのリクエスト数 (RPS) 流量制御
  • サービスごとのグローバル流量制御: アプリケーションごとではなく、サービスごとに流量制御を適用します。
  • 同時接続上限: 許容される同時接続の数を設定します。
4.1.6.1. 制限のタイプ
リンクのコピー

このポリシーでは、lua-resty-limit-traffic ライブラリーにより提供される以下の制限タイプがサポートされます。

  • leaky_bucket_limiters: 平均リクエスト数および最大バーストサイズをベースにした leaky_bucket アルゴリズムに基づきます。
  • fixed_window_limiters: 特定の期間 (最後の X 秒) に基づきます。
  • connection_limiters: 同時接続の数に基づきます。

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

4.1.6.2. 制限の定義
リンクのコピー

リミッターはキーを持ち、このキーで制限を定義するのに使用するエンティティーをエンコードします (IP、サービス、エンドポイント、ID、特定ヘッダーの値など)。キーは、リミッターの key パラメーターで指定します。

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

  • name: キーの名前です。スコープ内で一意でなければなりません。

  • scope: キーのスコープを定義します。サポートされるスコープは以下のとおりです。

    • service: 1 つのサービスに影響を及ぼすサービスごとのスコープ
    • global: すべてのサービスに影響を及ぼすグローバルスコープ

  • name_type:name の値がどのように評価されるかを定義します。

    • plain: プレーンテキストとして評価される。
    • liquid: Liquid として評価される。

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

  • leaky_bucket_limiters: rate および burst

    • rate: 遅延を生じることなく実行できる 1 秒あたりのリクエスト数を定義します。
    • burst: 許容レートを超えることのできる 1 秒あたりのリクエスト数を定義します。許容レート (rate で指定される) を超えるリクエストには、人為的な遅延が適用されます。1 秒あたりのリクエスト数が burst で定義されるレートを超えると、リクエストは拒否されます。
  • fixed_window_limiters: count、window。count は、window で定義される秒数あたりに実行できるリクエスト数を定義します。

  • connection_limiters: conn、burst、および delay

    • conn: 許容される同時接続の最大数を定義します。burst で定義される 1 秒あたりの接続数までこの値を超えることができます。
    • delay: 制限を超える接続を遅延させる秒数です。

例

  1. service_A に対するリクエストを毎分 10 回許可します。 

    {
  "key": { "name": "service_A" },
  "count": 10,
  "window": 60
}
    Copy to Clipboard Toggle word wrap

  2. burst および delay をそれぞれ 10 および 1 に設定して、100 の接続を許可します。 

    {
  "key": { "name": "service_A" },
  "conn": 100,
  "burst": 10,
  "delay": 1
}
    Copy to Clipboard Toggle word wrap

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

4.1.6.3. Liquid テンプレート
リンクのコピー

Edge Limiting ポリシーではキーに Liquid 変数がサポートされるので、動的なキーに制限を指定することができます。そのためには、キーの name_type パラメーターを liquid に設定する必要があります。これにより、name パラメーターに Liquid パラメーターを使用することができます。例: クライアント IP アドレスの場合は {{ remote_addr }}、JWT トークンの sub クレームの場合は {{ jwt.sub }}。

以下に例を示します。 

{
  "key": { "name": "{{ jwt.sub }}", "name_type": "liquid" },
  "count": 10,
  "window": 60
}
Copy to Clipboard Toggle word wrap

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

4.1.6.4. 条件の適用
リンクのコピー

条件は、API ゲートウェイがリミッターをいつ適用するかを定義します。各リミッターの condition プロパティーで少なくとも 1 つの操作を指定する必要があります。

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

  • combine_op。演算のリストに適用されるブール演算子です。or および and の 2 つの値がサポートされます。

  • operations。評価する必要がある条件のリストです。各演算は、以下のプロパティーを持つオブジェクトにより表されます。

    • left: 演算の左側部分
    • left_type: left プロパティーがどのように評価されるか (plain または liquid)。
    • right: 演算の右側部分
    • right_type: right プロパティーがどのように評価されるか (plain または liquid)。
    • op: 左右の部分の間に適用される演算子。== (等しい) および != (等しくない) の 2 つの値がサポートされます。

以下に例を示します。 

"condition": {
  "combine_op": "and",
  "operations": [
    {
      "op": "==",
      "right": "GET",
      "left_type": "liquid",
      "left": "{{ http_method }}",
      "right_type": "plain"
    }
  ]
}
Copy to Clipboard Toggle word wrap
4.1.6.5. ストアの設定
リンクのコピー

デフォルトでは、Edge Limiting ポリシーは流量制御カウンターに OpenResty 共有ディクショナリーを使用します。ただし、共有ディクショナリーの代わりに外部の Redis サーバーを使用することができます。この設定は、複数の APIcast インスタンスが使用されている場合に役立ちます。Redis サーバーは、redis_url パラメーターを使用して設定することができます。

4.1.6.6. エラー処理
リンクのコピー

リミッターでは、エラーの処理方法を設定するために以下のパラメーターがサポートされます。

  • limits_exceeded_error: 設定した上限を超えた際にクライアントに返されるエラーステータスコードおよびメッセージを設定することができます。以下のパラメーターを設定する必要があります。

    • status_code: 上限を超えた際のリクエストのステータスコード。デフォルトは 429 です。

    • error_handling: エラーの処理方法。

      • exit: エラーで応答します。
      • log: リクエストを通過させ、ログのみを出力します。

  • configuration_error: 設定が正しくない場合にクライアントに返されるエラーステータスコードおよびメッセージを設定することができます。以下のパラメーターを設定する必要があります。

    • status_code: 設定に問題がある場合のステータスコード。デフォルトは 500 です。

    • error_handling: エラーの処理方法。

      • exit: エラーで応答します。
      • log: リクエストを通過させ、ログのみを出力します。

4.1.7. Header Modification ポリシー
リンクのコピー

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

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

  • request: リクエストヘッダーに適用する操作のリスト
  • response: レスポンスヘッダーに適用する操作のリスト

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

  • op: 適用する操作を指定します。add 操作は既存のヘッダーに値を追加します。set 操作はヘッダーおよび値を作成し、既存のヘッダーの値が既に存在する場合はその値を上書きします。push 操作はヘッダーおよび値を作成しますが、既存のヘッダーの値が既に存在していてもその値を上書きしません。その代わりに、push は既存のヘッダーに値を追加します。delete 操作はヘッダーを削除します。
  • header: 作成または変更するヘッダーを指定します。ヘッダー名には任意の文字列を使用することができます (例: Custom-Header)。
  • value_type: ヘッダーの値がどのように評価されるかを定義します。プレーンテキストの場合の plain または Liquid テンプレートとして評価する場合の liquid いずれかに設定します。詳細は、「ポリシーでの変数およびフィルターの使用」 を参照してください。
  • value: ヘッダーに使用される値を指定します。値のタイプが liquid の場合には、値は {{ variable_from_context }} の形式にする必要があります。削除する場合には不要です。

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

{
  "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}}"
      }
    ]
  }
}
Copy to Clipboard Toggle word wrap

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

4.1.8. IP Check ポリシー
リンクのコピー

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

設定プロパティー

Expand
プロパティー説明データタイプ必須/任意

check_type

check_type プロパティーには、whitelist または blacklist の 2 つの値を指定することができます。blacklist は、リスト上の IP からのリクエストをすべて拒否します。whitelist は、リスト上に ない IP からのリクエストをすべて拒否します。

文字列 (whitelist または blacklist のどちらかでなければなりません)

必須

ips

ips プロパティーでは、ホワイトリストまたはブラックリストに登録する IP アドレスのリストを指定することができます。個別の IP および CIDR 範囲の両方を使用することができます。

文字列の配列 (有効な IP アドレスでなければなりません)

必須

error_msg

error_msg プロパティーを使用して、リクエストが拒否された時に返されるエラーメッセージを設定することができます。

文字列

任意

client_ip_sources

client_ip_sources プロパティーでは、クライアント IP の取得方法を設定することができます。デフォルトでは、最後に呼び出しを実施した IP が使用されます。これ以外のオプションは、X-Forwarded-For および X-Real-IP です。

文字列の配列。有効なオプションは、X-Forwarded-For、X-Real-IP、および last_caller です (複数の選択が可能です)。

任意

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

{
  "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"
  }
}
Copy to Clipboard Toggle word wrap

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

4.1.9. Liquid Context Debug ポリシー
リンクのコピー

注記

Liquid Context Debug ポリシーの想定は、開発環境でのデバッグ用途のみで、実稼働環境での使用は意図されていません。

このポリシーは 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",
    ...
  }
  ...
}
Copy to Clipboard Toggle word wrap

4.1.10. Logging ポリシー
リンクのコピー

Logging ポリシーにより、各 API サービスの APIcast (NGINX) アクセスログを個別に有効または無効にすることができます。デフォルトでは、このポリシーはポリシーチェーンで有効になっていません。

このポリシーは、enable_access_logs 設定パラメーターしかサポートしません。サービスのアクセスロギングを無効にするには、ポリシーを有効にし、enable_access_logs パラメーターの選択を解除して、Submit ボタンをクリックします。アクセスログを有効にするには、enable_access_logs パラメーターを選択するか、Logging ポリシーを無効にします。

ロギングポリシーの設定
View larger image
ロギングポリシーの設定

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

4.1.11. OAuth 2.0 Token Introspection ポリシー
リンクのコピー

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

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

use_3scale_oidc_issuer_endpoint

この設定では、APIcast はクライアント資格情報 (クライアント ID とクライアントシークレット) と、サービス統合ページで設定された OpenID Connect 発行者設定からのトークンイントロスペクションエンドポイントを使用します。

APIcast は、OpenID Connect 発行者の .well-known/openid-configuration エンドポイントが返す token_introspection_endpoint フィールドからトークンイントロスペクションエンドポイントを検出します。

例4.1 use_3scale_oidc_issuer_endpoint に設定された認証タイプ

以下は、認証タイプが use_3scale_oidc_issuer_endpoint に設定されている場合の設定例です。 

"policy_chain": [
…​
  {
    "name": "apicast.policy.token_introspection",
    "configuration": {
      "auth_type": "use_3scale_oidc_issuer_endpoint"
    }
  }
…​
],
Copy to Clipboard Toggle word wrap
client_id+client_secret

このオプションでは、APIcast がトークン情報を要求するのに使用するクライアント ID およびクライアントシークレットと共に、異なるトークンイントロスペクションエンドポイントを指定することができます。

このオプションを使用する場合には、以下の設定パラメーターを定義します。

  • client_id: トークンイントロスペクションエンドポイント用のクライアント ID を設定します。
  • client_secret: トークンイントロスペクションエンドポイント用のクライアントシークレットを設定します。

  • introspection_url: イントロスペクションエンドポイントの URL を設定します。

    例4.2 client_id+client_secret に設定された認証タイプ

    以下は、認証タイプが client_id+client_secret に設定されている場合の設定例です。 

    "policy_chain": [
…​
  {
    "name": "apicast.policy.token_introspection",
    "configuration": {
      "auth_type": "client_id+client_secret",
      "client_id": "myclient",
      "client_secret": "mysecret",
      "introspection_url": "http://red_hat_single_sign-on/token/introspection"
    }
  }
…​
],
    Copy to Clipboard Toggle word wrap

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

OAuth 2.0 Token Introspection Configuration
View larger image
OAuth 2.0 Token Introspection Configuration

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

  • true: 呼び出しを承認します
  • false: Authentication Failed エラーと共に呼び出しを拒否します

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

4.1.12. Referrer ポリシー
リンクのコピー

Referrer ポリシーを使用すると、参照元フィルター機能が有効になります。サービスポリシーチェーンでこのポリシーが有効な場合には、APIcast は今後のリクエストの Referer ポリシーの値を referrer パラメーターで Service Management API (AuthRep 呼び出し) に送信します。参照元フィルター機能の仕組みの詳細は、Authentication Patterns の Referrer Filtering セクションを参照してください。

4.1.13. RH-SSO/Keycloak Role Check ポリシー
リンクのコピー

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

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

  • whitelist (デフォルト): whitelist が使用されると、APIcast は指定したスコープが JWT トークンに含まれるかどうかを確認し、JWT にそのスコープがなければ呼び出しを拒否します。
  • blacklist: blacklist が使用された場合には、JWT トークンにブラックリスト登録したスコープが含まれていれば APIcast は呼び出しを拒否します。

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

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

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

  • resource: ロールによって制御されるリソース (エンドポイント)。これは、マッピングルールと同じフォーマットです。文字列の先頭からパターンの照合を行います。完全一致の場合には、最後に $ を追加する必要があります。

  • resource_type: このプロパティーで、resource の値がどのように評価されるかを定義します。

    • プレーンテキストとして (plain): resource の値をプレーンテキストとして評価します。たとえば /api/v1/products$。
    • Liquid テキストとして (liquid): resource の値に Liquid を使用することを許可します。例: /resource_{{ jwt.aud }} は、クライアント ID (JWT aud クレームに含まれる) を含むリソースへのアクセスを管理します。

  • realm_roles: レルムロールを確認する場合に使用します (Red Hat Single Sign-On のレルムロール に関するドキュメントを参照してください)。

    レルムロールは、Red Hat Single Sign-On により発行された JWT にあります。 

      "realm_access": {
    "roles": [
      "<realm_role_A>", "<realm_role_B>"
    ]
  }
    Copy to Clipboard Toggle word wrap

    実際のロールは、ポリシーで指定する必要があります。 

    "realm_roles": [
  { "name": "<realm_role_A>" }, { "name": "<realm_role_B>" }
]
    Copy to Clipboard Toggle word wrap

    realm_roles 配列の各オブジェクトでは、以下のプロパティーを使用することができます。

  • name: ロールの名前を指定します。
  • name_type: plain または liquid のどちらかを指定して、name がどのように評価されるかを定義します (resource_type の場合と同じように機能します)。

  • client_roles: クライアント namespace に特定のアクセ出力ルがあるかどうかを確認する場合に、client_roles を使用します (Red Hat Single Sign-On のクライアントロール に関するドキュメントを参照してください)。

    クライアントロールは、JWT の resource_access クレームのセクションにあります。 

      "resource_access": {
    "<client_A>": {
      "roles": [
        "<client_role_A>", "<client_role_B>"
      ]
    },
    "<client_B>": {
      "roles": [
        "<client_role_A>", "<client_role_B>"
      ]
    }
  }
    Copy to Clipboard Toggle word wrap

    ポリシーでクライアントロールを指定します。 

    "client_roles": [
  { "name": "<client_role_A>", "client": "<client_A>" },
  { "name": "<client_role_B>", "client": "<client_A>" },
  { "name": "<client_role_A>", "client": "<client_B>" },
  { "name": "<client_role_B>", "client": "<client_B>" }
]
    Copy to Clipboard Toggle word wrap

    client_roles 配列の各オブジェクトでは、以下のプロパティーを使用することができます。

  • name: ロールの名前を指定します。
  • name_type: plain または liquid のどちらかを指定して、name の値がどのように評価されるかを定義します (resource_type の場合と同じように機能します)。
  • client: ロールのクライアントを指定します。定義しなければ、このポリシーはクライアントに aud クレームを使用します。
  • client_type: plain または liquid のどちらかを指定して、client の値がどのように評価されるかを定義します (resource_type の場合と同じように機能します)。

4.1.14. Routing ポリシー
リンクのコピー

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

ルーティングは、以下のルールに基づきます。

APIcast ポリシーと組み合わせる場合には、ポリシーチェーンでは APIcast ポリシーの前に Routing ポリシーを設定する必要があります。2 つのポリシーのうち始めのポリシーがレスポンスにコンテンツを出力するためです。2 番目のポリシーにコンテンツフェーズを実行する変更が加えられても、リクエストはすでにクライアントに送信されるため、レスポンスには何も出力されません。

4.1.14.1. ルーティングルール
リンクのコピー
  • 複数のルールが存在する場合、最初の一致が適用されます。ルールは順序付けられます。
  • ルールが適用されない場合は、アップストリームに適用されるため、ポリシーは、プライベートベース URL であるサービス設定からアップストリームを取得する APIcast ポリシーと組み合わせて機能します。
4.1.14.2. リクエストパスルール
リンクのコピー

以下の設定では、パスが /accounts の場合に http://example.com にルーティングします。 

{
   "name": "routing",
   "version": "builtin",
   "configuration": {
     "rules": [
       {
         "url": "http://example.com",
         "condition": {
           "operations": [
             {
               "match": "path",
               "op": "==",
               "value": "/accounts"
             }
           ]
         }
       }
     ]
   }
 }
Copy to Clipboard Toggle word wrap
4.1.14.3. ヘッダールール
リンクのコピー

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

{
   "name": "routing",
   "version": "builtin",
   "configuration": {
     "rules": [
       {
         "url": "http://example.com",
         "condition": {
           "operations": [
             {
               "match": "header",
               "header_name": "Test-Header",
               "op": "==",
               "value": "123"
             }
           ]
         }
       }
     ]
   }
 }
Copy to Clipboard Toggle word wrap
4.1.14.4. クエリー引数ルール
リンクのコピー

以下の設定では、クエリー引数 test_query_arg の値が 123 の場合に http://example.com にルーティングします。 

{
   "name": "routing",
   "version": "builtin",
   "configuration": {
     "rules": [
       {
         "url": "http://example.com",
         "condition": {
           "operations": [
             {
               "match": "query_arg",
               "query_arg_name": "test_query_arg",
               "op": "==",
               "value": "123"
             }
           ]
         }
       }
     ]
   }
 }
Copy to Clipboard Toggle word wrap
4.1.14.5. JWT クレームルール
リンクのコピー

JWT クレームの値に基づいてルーティングするためには、ポリシーチェーンには、ポリシーが共有するコンテキストで JWT を検証して格納するポリシーが必要です。

以下の設定では、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"
             }
           ]
         }
       }
     ]
   }
 }
Copy to Clipboard Toggle word wrap
4.1.14.6. 複数演算ルール
リンクのコピー

ルールに複数の演算を設定し、すべてが true と評価される場合にだけ (andcombine_op を使用) 指定したアップストリームにルーティングすることや、少なくとも 1 つが true と評価される場合に (orcombine_op を使用) 指定したアップストリームにルーティングすることができます。combine_op のデフォルト値は and です。

以下の設定では、リクエストのパスが /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"
             }
           ]
         }
       }
     ]
   }
 }
Copy to Clipboard Toggle word wrap

以下の設定では、リクエストのパスが /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"
             }
           ]
         }
       }
     ]
   }
 }
Copy to Clipboard Toggle word wrap
4.1.14.7. ルールの結合
リンクのコピー

ルールを組み合わせることができます。複数のルールがある場合、選択されるアップストリームは、true と評価される最初のルールです。

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

{
   "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"
             }
           ]
         }
       }
     ]
   }
 }
Copy to Clipboard Toggle word wrap
4.1.14.8. キャッチオールルール
リンクのコピー

演算のないルールは常にマッチします。これは、キャッチオールルールを定義するのに役立ちます。

以下の設定では、パスが /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": []
         }
       }
     ]
   }
 }
Copy to Clipboard Toggle word wrap
4.1.14.9. サポートされる操作
リンクのコピー

サポートされる演算は、==、!=、および matches です。最後の演算は正規表現を使用する文字列との照合を行い、ngx.re.match を使用して実装されます。

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

{
   "name": "routing",
   "version": "builtin",
   "configuration": {
     "rules": [
       {
         "url": "http://example.com",
         "condition": {
           "operations": [
             {
               "match": "path",
               "op": "!=",
               "value": "/accounts"
             }
           ]
         }
       }
     ]
   }
 }
Copy to Clipboard Toggle word wrap
4.1.14.10. Liquid テンプレート
リンクのコピー

設定の値に liquid テンプレートを使用することができます。これにより、チェーン内のポリシーがコンテキストにキー my_var を保存する場合には、動的な値を使用してルールを定義することができます。

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

{
   "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"
             }
           ]
         }
       }
     ]
   }
 }
Copy to Clipboard Toggle word wrap
4.1.14.11. Host ヘッダーで使用されるホストの設定
リンクのコピー

リクエストがルーティングされる際に、デフォルトでは、ポリシーはマッチしたルールの URL のホストを使用して Host ヘッダーを設定します。host_header 属性を使用して別のホストを指定することができます。

以下の設定では、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": "/"
             }
           ]
         }
       }
     ]
   }
 }
Copy to Clipboard Toggle word wrap

4.1.15. Prometheus メトリクス
リンクのコピー

Prometheus はスタンドアロンのオープンソースのシステムモニターリングおよびアラート用ツールキットです。

重要

Red Hat 3scale の本リリースでは、Prometheus のインストールおよび設定はサポートされていません。オプションとして、コミュニティーバージョンの Prometheus を使用して、APIcast 管理下の API サービスのメトリクスおよびアラートを視覚化することができます。

Prometheus メトリクスの可用性

APIcast と Prometheus のインテグレーションは、以下のデプロイメントオプションで利用することができます。

  • Self-managed APIcast (ホスト型 API Management およびオンプレミス型 API Management 両方との組み合わせに対応)
  • Embedded APIcast (オンプレミス型 API Management)
注記

APIcast と Prometheus のインテグレーションは、ホスト型 API Management と Hosted APIcast の組み合わせでは利用することができません。

Prometheus メトリクスのリスト

以下のメトリクスは常に使用可能です。

Expand
メトリクス説明タイプラベル

nginx_http_connections

HTTP 接続の数

ゲージ

state (accepted、active、handled、reading、total、waiting、writing)

nginx_error_log

APIcast エラー

カウンター

level (debug、info、notice、warn、error、crit、alert、emerg)

openresty_shdict_capacity

ワーカー間で共有されるディクショナリーの容量

ゲージ

dict (すべてのディクショナリーで共通)

openresty_shdict_free_space

ワーカー間で共有されるディクショナリーの空き容量

ゲージ

dict (すべてのディクショナリーで共通)

nginx_metric_errors_total

メトリクスを管理する Lua ライブラリーのエラーの数

カウンター

-

total_response_time_seconds

クライアントにレスポンスを送信するのに必要な時間 (秒単位)

ヒストグラム

-

upstream_response_time_seconds

アップストリームサーバーからの応答時間 (秒単位)

ヒストグラム

-

upstream_status

アップストリームサーバーからの HTTP ステータス

カウンター

status

threescale_backend_calls

3scale バックエンド (Apisonator) に対する承認および報告リクエスト

カウンター

エンドポイント (authrep、auth、report)、ステータス (2xx、4xx、5xx)

以下のメトリクスは、3scale Batcher ポリシーを使用する場合にのみ使用可能です。

Expand
メトリクス説明タイプラベル

batching_policy_auths_cache_hits

3scale Batcher ポリシーの承認キャッシュのヒット数

カウンター

-

batching_policy_auths_cache_misses

3scale Batcher ポリシーの承認キャッシュのミス数

カウンター

-

値を持たないメトリクス

メトリクスが値を持たない場合には、メトリクスは非表示になります。たとえば、nginx_error_log に報告するエラーがない場合、nginx_error_log メトリックは表示されません。値を持った場合にのみ表示されます。

4.1.16. SOAP ポリシー
リンクのコピー

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

設定プロパティー

Expand
プロパティー説明値必須/任意

pattern

pattern プロパティーにより、APIcast がマッチを探す SOAPAction URI の文字列を指定することができます。

データタイプ: 文字列

必須

metric_system_name

metric_system_name プロパティーを使用して、マッチしたパターンがヒットを登録する 3scale バックエンドメトリクスを指定することができます。

データタイプ: 文字列 (有効な メトリクス でなければなりません)

必須

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

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

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

4.1.17. TLS Client Certificate Validation ポリシー
リンクのコピー

4.1.17.1. TLS Client Certificate Validation ポリシーの概要
リンクのコピー

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

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

4.1.17.2. TLS Client Certificate Validation ポリシーに対応する APIcast の設定
リンクのコピー

TLS を終端するように APIcast を設定する必要があります。以下の手順に従って、Client Certificate Validation ポリシーが設定された APIcast でユーザーが提供するクライアント証明書を検証するように設定します。

4.1.17.2.1. 前提条件:
リンクのコピー
  • 3scale システムにアクセスできること。
  • すべてのデプロイメントが完了していること。
4.1.17.2.2. ポリシーに対応する APIcast のセットアップ
リンクのコピー

APIcast をセットアップし TLS を終端するように設定するには、以下の手順に従います。

  1. OpenShift テンプレートを使用した APIcast のデプロイ に記載の手順に従って、アクセストークンを取得し Self-managed APIcast をデプロイする必要があります。

    注記

    ゲートウェイ全体で特定の証明書を使用するように APIcast インスタンスを再設定しなければならないので、Self-managed APIcast のデプロイメントが必要です。

  2. テストを簡素化するために、--param フラグを指定してレイジーローダー、キャッシュなし、およびステージング環境を使用することができます (ただし、テスト目的の場合のみ)。 

    oc new-app -f https://raw.githubusercontent.com/3scale/3scale-amp-openshift-templates/2.5.0.GA/apicast-gateway/apicast.yml --param CONFIGURATION_LOADER=lazy --param DEPLOYMENT_ENVIRONMENT=staging --param CONFIGURATION_CACHE=0
    Copy to Clipboard Toggle word wrap
  3. テスト用途の証明書を生成します。なお、実稼働環境のデプロイメントの場合には、認証局から提供された証明書を使用することができます。

  4. TLS 証明書を使用してシークレットを作成します。 

    oc create secret tls apicast-tls
--cert=ca/certs/server.crt
--key=ca/keys/server.key
    Copy to Clipboard Toggle word wrap

  5. APIcast デプロイメント内にシークレットをマウントします。 

    oc set volume dc/apicast --add --name=certificates --mount-path=/var/run/secrets/apicast --secret-name=apicast-tls
    Copy to Clipboard Toggle word wrap

  6. HTTPS 用ポート 8443 のリッスンを開始するように APIcast を設定します。 

    oc set env dc/apicast APICAST_HTTPS_PORT=8443 APICAST_HTTPS_CERTIFICATE=/var/run/secrets/apicast/tls.crt APICAST_HTTPS_CERTIFICATE_KEY=/var/run/secrets/apicast/tls.key
    Copy to Clipboard Toggle word wrap

  7. サービスでポート 8443 を公開します。 

    oc patch service apicast -p '{"spec":{"ports":[{"name":"https","port":8443,"protocol":"TCP"}]}}'
    Copy to Clipboard Toggle word wrap

  8. デフォルトルートを削除します。 

    oc delete route api-apicast-staging
    Copy to Clipboard Toggle word wrap

  9. apicast サービスをルートとして公開します。 

    oc create route passthrough --service=apicast --port=https --hostname=api-3scale-apicast-staging.$WILDCARD_DOMAIN
    Copy to Clipboard Toggle word wrap
    注記

    このステップは、使用するすべての API で実施する必要があります (それぞれの API のドメインに変更してください)。

  10. プレースホルダーの [Your_user_key] に実際のキーを指定して、上記のステップでデプロイしたゲートウェイが機能し、設定が保存されていることを確認します。 

    curl https://api-3scale-apicast-staging.$WILDCARD_DOMAIN?user_key=[Your_user_key] -v --cacert ca/certs/ca.crt
    Copy to Clipboard Toggle word wrap
4.1.17.3. ポリシーチェーンへの TLS Client Certificate Validation ポリシーの設定
リンクのコピー
4.1.17.3.1. 前提条件
リンクのコピー
4.1.17.3.2. ポリシーの設定
リンクのコピー
  1. 管理ポータルでのポリシーの有効化 に記載の手順に従って TLS Client Certificate Validation を選択し、API に TLS Client Certificate Validation ポリシーを追加します。
  2. TLS Client Certificate Validation のリンクをクリックします。
  3. Enabled のチェックボックスを選択し、ポリシーを有効にします。
  4. 証明書をホワイトリストに追加するには、プラス (+) アイコンをクリックします。
  5. -----BEGIN CERTIFICATE----- および -----END CERTIFICATE----- を含めて、証明書を指定します。
  6. API への TLS Client Certificate Validation ポリシーの設定が完了したら、Update Policy をクリックします。

付加手順:

  • プラス (+) アイコンをクリックして、さらに証明書を追加することができます。
  • 上/下矢印を使用して、証明書の順番を入れ替えることもできます。

変更を保存するには、Update & test in Staging Environment をクリックします。

4.1.17.4. TLS Client Certificate Validation ポリシー機能の確認
リンクのコピー
4.1.17.4.1. 前提条件
リンクのコピー
4.1.17.4.2. ポリシー機能の確認
リンクのコピー

プレースホルダーの [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
Copy to Clipboard Toggle word wrap
4.1.17.5. ホワイトリストからの証明書の削除
リンクのコピー
4.1.17.5.1. 前提条件
リンクのコピー
4.1.17.5.2. 証明書の削除
リンクのコピー
  1. TLS Client Certificate Validation のリンクをクリックします。
  2. x アイコンをクリックし、ホワイトリストから証明書を削除します。
  3. 証明書の削除が完了したら、Update Policy をクリックします。

変更を保存するには、Update & test in Staging Environment をクリックします。

4.1.17.6. リファレンス資料
リンクのコピー

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

4.1.18. Upstream ポリシー
リンクのコピー

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

例:

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

ポリシーチェーンの参照

Expand
プロパティー説明値必須/任意

regex

regex プロパティーを使用して、Upstream ポリシーがリクエストパスを照合する際に使用する正規表現を指定することができます。

データタイプ: 文字列 (有効な正規表現の構文でなければなりません)

必須

url

url プロパティーを使用して、マッチした場合に置き換える URL を指定することができます。Upstream ポリシーはこの URL が有効かどうかを確認しない点に注意してください。

データタイプ: 文字列 (有効な URL でなければなりません)

必須

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

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

      }
    ]
  }
}
Copy to Clipboard Toggle word wrap

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

4.1.19. URL Rewriting ポリシー
リンクのコピー

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

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

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

  • commands: リクエストのパスを書き換えるために適用されるコマンドのリスト。
  • query_args_commands: リクエストのクエリー文字列を書き換えるために適用されるコマンドのリスト。
4.1.19.1. パスを書き換えるためのコマンド
リンクのコピー

commands リストの各コマンドは、以下の設定パラメーターで設定されます。

  • op: 適用される操作。設定可能なオプションは sub および gsub です。sub 操作では、指定した正規表現との最初のマッチだけが置き換えられます。gsub 操作では、指定した正規表現とのマッチがすべて置き換えられます。sub および gsub 操作に関するドキュメントを参照してください。
  • regex: 照合される Perl 互換の正規表現
  • replace: マッチした際に置き換えられる文字列
  • options (オプション): 正規表現との照合がどのように行われるかを定義するオプション。設定可能なオプションに関する情報は、OpenResty Lua モジュールプロジェクトのドキュメントの ngx.re.match セクションを参照してください。
  • break (オプション): true に設定すると (チェックボックスを選択する)、コマンドが URL を書き換えた場合、それが適用される最後のコマンドになります (リスト内の後続コマンドはすべて破棄されます)。
4.1.19.2. クエリー文字列を書き換えるためのコマンド
リンクのコピー

query_args_commands リストの各コマンドは、以下の設定パラメーターで設定されます。

  • op: クエリー引数に適用される操作。以下のオプションを設定することができます。

    • add: 既存の引数に値を追加します。
    • set: 引数が設定されていなければ作成し、設定されていればその値を置き換えます。
    • push: 引数が設定されていなければ作成し、設定されていれば値を追加します。
    • delete: 引数を削除します。
  • arg: 操作が適用されるクエリー引数の名前
  • value: クエリー引数に使用される値を指定します。値のタイプが liquid の場合には、値は {{ variable_from_context }} の形式にする必要があります。delete 操作の場合には、値を考慮する必要はありません。
  • value_type (オプション): クエリー引数の値がどのように評価されるかを定義します。プレーンテキストの場合の plain または Liquid テンプレートとして評価する場合の liquid いずれかに設定します。詳細は、「ポリシーでの変数およびフィルターの使用」 を参照してください。指定しなければ、デフォルトではタイプ plain が使用されます。

例

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

{
  "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"
      }
    ]
  }
Copy to Clipboard Toggle word wrap

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

https://api.example.com/api/v1/products/123/details?user_key=abc123secret&pusharg=first&setarg=original
Copy to Clipboard Toggle word wrap

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

https://api-backend.example.com/internal/products/123/details?pusharg=first&pusharg=pushvalue&setarg=setvalue
Copy to Clipboard Toggle word wrap

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

  1. サブストリング /api/v1/ はパス書き換えコマンドだけにマッチし、/internal/ に置き換えられます。
  2. user_key クエリー引数は削除されます。
  3. 値 pushvalue は追加の値として pusharg クエリー引数に追加されます。
  4. クエリー引数 setarg の値 original は、設定した値 setvalue に置き換えられます。
  5. クエリー引数 addarg は元の URL に存在しないため、コマンド add は適用されませんでした。

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

4.1.20. URL Rewriting with Captures ポリシー
リンクのコピー

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

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

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

  • match_rule: このルールは受信したリクエストの URL と照合されます。このルールには {nameOfArgument} 形式の名前付き引数を含めることができ、これらの引数を書き換えられる URL で使用することができます。URL は正規表現として match_rule と比較されます。名前付き引数と照合する値には、[\w-.~%!$&'()*+,;=@:]+ の文字しか使用することができません (PCRE 正規表現表記)。他の正規表現トークンを match_rule の表記で使用することができます。たとえば、文字列先頭の ^ および文字列末尾の $ 等です。
  • template: URL のテンプレートで、これにより元の URL が書き換えられます。match_rule からの名前付き引数を使用することができます。

元の 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"
      }
    ]
  }
}
Copy to Clipboard Toggle word wrap

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

https://api.example.com/api/v1/products/123/details?user_key=abc123secret
Copy to Clipboard Toggle word wrap

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

https://api-backend.example.com/internal/products/details?user_key=abc123secret&extraparam=anyvalue&id=123
Copy to Clipboard Toggle word wrap

4.2. 標準ポリシーの有効化
リンクのコピー

管理ポータルでポリシーを有効にするには、以下の手順を実施します。

  1. 3scale にログインします。
  2. API service に移動します。
  3. [your_API_name] > Integration > Configuration の順に移動し、edit APIcast configuration を選択します。
  4. POLICIES セクションで Add Policy をクリックします。
  5. 追加するポリシーを選択し、必須フィールドに入力します。
  6. Update & test in Staging Environment ボタンをクリックし、ポリシーチェーンを保存します。

4.3. カスタム APIcast ポリシーの作成
リンクのコピー

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

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

  • ポリシーは Lua で記述される。
  • ポリシーは適切なファイルディレクトリーに保管しなければならない。
  • ポリシーチェーン内での設定場所により、ポリシーの動作が異なる。
  • カスタムポリシーを追加するインターフェイスは完全にサポートされているが、カスタムポリシー自体はサポートされていない。

4.4. APIcast へのカスタムポリシーの追加
リンクのコピー

カスタムポリシーを作成したら、それを APIcast に追加する必要があります。その手順は、APIcast がデプロイされている場所により異なります。

以下に示す Self-managed APIcast デプロイメントに、カスタムポリシーを追加することができます。

  • Embedded APIcast ゲートウェイ (OpenShift 上の 3scale オンプレミスデプロイメントの一部)
  • OpenShift および Docker コンテナー環境上の APIcast

カスタムポリシーを Hosted APIcast に追加することはできません。

警告

決して、実稼働環境のゲートウェイで直接ポリシーを変更しないでください。変更を必ずテストしてください。

4.4.1. Embedded APIcast へのカスタムポリシーの追加
リンクのコピー

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

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

警告

apicast-custom-policies をビルドすると、ビルドプロセスは新しいイメージを amp-apicast:latest タグにプッシュします。このイメージストリームタグ (:latest) でイメージが変更されると、デフォルトでは apicast-staging および apicast-production タグの両方が自動的に新しいデプロイメントを開始するように設定されています。実稼働環境 (あるいは、必要であればステージング環境) のサービスが中断されるのを避けるためには、自動デプロイメントを無効にするか (Automatically start a new deployment when the image changesチェックボックス) か、実稼働環境用に別のイメージストリームタグ (例: amp-apicast:production) を設定することをお勧めします。

カスタムポリシーをオンプレミスデプロイメントに追加するには、以下の手順に従います。

  1. https://github.com/3scale/apicast-example-policy (ポリシーの例が含まれる公開リポジトリー) をフォークするか、そのコンテンツが含まれるプライベートリポジトリーを作成します。OpenShift がイメージをビルドするには、Git リポジトリーでカスタムポリシーのコードが必要です。プライベート Git リポジトリーを使用するには、OpenShift でシークレットを設定する必要がある点に注意してください。
  2. リポジトリーをローカルにクローンし、ポリシーの実装を追加し、変更をご自分の Git リポジトリーにプッシュします。

  3. openshift.yml テンプレートを更新します。具体的には、以下のパラメーターを変更します。

    1. spec.source.git.uri: https://github.com/3scale/apicast-example-policy.git (ポリシーの BuildConfig): ご自分の Git リポジトリーの場所に変更します。
    2. spec.source.images[0].paths.sourcePath: /opt/app-root/policies/example (カスタムポリシーの BuildConfig): example をリポジトリーの policies ディレクトリーに追加したカスタムポリシーの名前に変更します。
    3. オプションで、OpenShift オブジェクト名およびイメージタグを更新します。ただし、変更の一貫性が維持されるようにする必要があります (例: apicast-example-policy BuildConfig が apicast-policy:example イメージをビルドおよびプッシュし、それを apicast-custom-policies BuildConfig がソースとして使用する。これによりダグの一貫性が維持されます)。

  4. 以下のコマンドを実行して OpenShift オブジェクトを作成します。 

    oc new-app -f openshift.yml --param AMP_RELEASE=2.5.0
    Copy to Clipboard Toggle word wrap

  5. ビルドが自動的に開始されない場合には、以下の 2 つのコマンドを実行します。apicast-example-policy を変更している場合には、ご自分の BuildConfig 名に置き換えます (例: apicast-<name>-policy)。最初のコマンドが完了するのを待ってから、2 番目のコマンドを実行してください。 

    oc start-build apicast-example-policy
oc start-build apicast-custom-policies
    Copy to Clipboard Toggle word wrap

Embedded APIcast のイメージに amp-apicast:latest イメージストリームの変更を追跡するトリガーがある場合には、APIcast の新しいデプロイメントが開始されます。apicast-staging が再開されたら管理ポータルの Integration ページに移動し、Add Policy ボタンをクリックしてご自分のカスタムポリシーがリストに表示されるのを確認します。カスタムポリシーを選択して設定したら、Update & test in Staging Environment をクリックし、カスタムポリシーをステージング APIcast で動作状態にします。

4.4.2. 別の OpenShift Container Platform 上の APIcast へのカスタムポリシーの追加
リンクのコピー

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

別の OpenShift Container Platform 上の APIcast にカスタムポリシーを追加します

  1. Embedded APIcast にポリシーを追加します。
  2. APIcast ゲートウェイをメインの OpenShift クラスターにデプロイしていない場合には、メインの OpenShift クラスター上の内部レジストリーへの アクセスを確立します。
  3. 3scale 2.5 APIcast OpenShift テンプレートを ダウンロードします。

  4. テンプレートを変更するには、デフォルトの image ディレクトリーを内部レジストリーの完全なイメージ名に置き換えます。 

    image: <registry>/<project>/amp-apicast:latest
    Copy to Clipboard Toggle word wrap

  5. カスタマイズしたイメージを指定し、OpenShift テンプレートを使用して APIcast をデプロイします。 

    oc new-app -f customizedApicast.yml
    Copy to Clipboard Toggle word wrap

4.5. 3scale でのポリシーチェーンの作成
リンクのコピー

APIcast ゲートウェイ設定の一部として、3scale でポリシーチェーンを作成します。UI でポリシーチェーンを変更するには、以下の手順に従います。

  1. AMP にログインします。

  2. API サービスに移動します。

    navigate to APIcast integrations page
    View larger image
    navigate to APIcast integrations page

  3. [your_API_name] > Integration > Configuration の順に移動し、edit APIcast configuration を選択します。

    navigate to APIcast configuration page
    View larger image
    navigate to APIcast configuration page

  4. POLICIES セクションで、矢印アイコンを使用してポリシーチェーン内のポリシーの順番を変更します。必ず APIcast ポリシーをポリシーチェーンの最後に設定します。

    policyChainOverview
    View larger image
    policyChainOverview
  5. Update & test in Staging Environment ボタンをクリックし、ポリシーチェーンを保存します。

4.6. ポリシーチェーン JSON 設定ファイルの作成
リンクのコピー

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

ポリシーチェーン 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",
          }
        ]
      }
    }
  ]
}
Copy to Clipboard Toggle word wrap

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

第5章 ポリシーチェーンと APIcast ネイティブデプロイメントのインテグレーション
リンクのコピー

ネイティブ APIcast デプロイメントの場合、THREESCALE_CONFIG_FILE 環境変数を使用して設定ファイルを指定することにより、カスタムポリシーチェーン を統合することができます。以下の例では、設定ファイル example.json を指定しています。 

THREESCALE_CONFIG_FILE=example.json bin/apicast
Copy to Clipboard Toggle word wrap

5.1. ポリシーでの変数およびフィルターの使用
リンクのコピー

一部の「APIcast 標準ポリシー」では Liquid テンプレートがサポートされます。Liquid テンプレートにより、通常の文字列値だけでなくリクエストのコンテキストに存在する変数も使用することができます。

コンテキスト変数を使用するには、その名前を {{ および }} で囲みます (例: {{ uri }})。変数がオブジェクトの場合には、その属性にもアクセスすることができます (例: {{ somevar.attr }})。

すべてのポリシーで使用することのできる標準の変数を以下に示します。

  • uri: クエリーパラメーターを含まないリクエストのパス (埋め込まれた NGINX 変数 $uri の値)。
  • host: リクエストのホスト (組み込まれた NGINX 変数 $host の値)
  • remote_addr: クライアントの IP アドレスト (組み込まれた NGINX 変数 $remote_addr の値)
  • headers: リクエストヘッダーが含まれるオブジェクト。特定のヘッダーの値を取得するには、{{headers['Some-Header']}} を使用します。
  • http_method: リクエストのメソッド (GET、POST 等)

変数は、リクエストの コンテキスト で使用できます。ポリシーは、追加の変数をコンテキストに追加できます。これらの変数は、変数が追加されたフェーズの後に使用されるフェーズが実行される場合、ポリシーチェーン内の同じポリシーまたは他のポリシーで使用できます。変数が追加されたポリシーの後に表示されるポリシーで変数が使用されている場合も、同じフェーズになる可能性があります。

標準の 3scale APIcast ポリシーでコンテキストに追加される変数の例を以下に示します。

  • jwt: 解析された JWT トークンの JSON ペイロード (OpenID Connect 認証用)
  • credentials: アプリケーションのクレデンシャルを保持するオブジェクト。たとえば "app_id": "972f7b4f"、"user_key": "13b668c4d1e10eaebaa5144b4749713f" 等。
  • service: 現在のリクエストが処理されるサービスの設定を保持するオブジェクト。たとえば、サービス ID は {{ service.id }} として利用可能です。

コンテキストで使用することのできるオブジェクトおよび値の完全なリストは、「Liquid Context Debug ポリシー」を参照してください。

変数は Liquid テンプレートの機能を活用して使用されます。たとえば {{ remote_addr }}、{{ headers['Some-Header'] }}、{{ jwt.aud }} 等。値に変数をサポートするポリシーは、_type 接尾辞が付く特殊なパラメーターを持ちます (例: value_type、name_type 等)。このパラメーターには、2 つの値を設定することができます (プレーンテキストの場合の plain および liquid テンプレートの場合の liquid)。

APIcast では、変数の値に適用することのできる Liquid フィルターもサポートされます。フィルターは Liquid 変数の値に NGINX 関数を適用します。

フィルターは変数出力タグ {{ }} で囲み、変数の名前または実際の値、パイプ記号 |、およびフィルター名の順に定義します。例: {{ 'username:password' | encode_base64 }}、{{ uri | escape_uri }}

パラメーターを必要としないフィルターもあります。この場合には、変数の代わりに空の文字列を使用することができます。たとえば、{{ '' | utctime }} は現在の時刻を TUC タイムゾーンで返します。

フィルターは、{{ variable | function1 | function2 }} のようにつなげることができます。たとえば {{ '' | utctime | escape_uri }}。

利用可能な関数のリストを以下に示します。

第6章 APIcast の環境変数
リンクのコピー

APIcast の環境変数を使用すると、APIcast の動作を変更することができます。サポートされている環境変数の値を以下に示します。

注記
  • サポートされていない環境変数および非推奨の環境変数は記載されていません
  • 一部の環境変数の機能は、APIcast ポリシーに移されています

APICAST_BACKEND_CACHE_HANDLER

値: strict | resilient

デフォルト: strict

非推奨: この環境変数の代わりに、Caching ポリシーを使用してください。

バックエンドにアクセスすることができない場合に、承認キャッシュがどのように動作するかを定義します。strict に設定すると、バックエンドにアクセスすることができない場合にキャッシュされたアプリケーションを削除します。resilient に設定すると、バックエンドから承認が拒否された場合にのみキャッシュされたアプリケーションを削除します。

APICAST_CONFIGURATION_CACHE

値: 数字

デフォルト: 0

設定を保存する間隔 (秒単位) を指定します。0 (ブート値の APICAST_CONFIGURATION_LOADER との互換性はない) または 60 より大きい値を設定する必要があります。たとえば、APICAST_CONFIGURATION_CACHE を 120 に設定すると、ゲートウェイは 2 分 (120 秒) ごとに設定を API Manager から読み込み直します。負の値を設定すると、再読み込みは無効になります。

APICAST_CONFIGURATION_LOADER

値: boot | lazy

デフォルト: lazy

設定の読み込み方法を定義します。boot に設定すると、ゲートウェイの起動時に API Manager に設定を要求します。lazy に設定すると、リクエストを受信するたびに設定を読み込みます (リクエストのたびに完全にリフレッシュするには、APICAST_CONFIGURATION_CACHE を 0 に設定する必要があります)。

APICAST_CUSTOM_CONFIG

非推奨: この環境変数の代わりに、policies を使用してください。

既存の APIcast ロジックをオーバーライドするカスタムロジックを実装する Lua モジュールの名前を定義します。

APICAST_ENVIRONMENT

デフォルト:

値: 文字列[:]

例: production:cloud-hosted

APIcast が読み込む環境 (またはパス) のコロン (:) 区切りリスト。CLI の -e または ---environment パラメーターの代わりに使用することができ、たとえばデフォルト環境としてコンテナーイメージに保存されます。CLI で渡される値は、常にこの変数に優先します。

APICAST_LOG_FILE

デフォルト: stderr

OpenResty エラーログが含まれるファイルを定義します。このファイルは、bin/apicast の error_log ディレクティブで使用されます。詳細は、NGINX のドキュメント を参照してください。ファイルパスは、絶対パスまたは APIcast プリフィックスディレクトリーへの相対パスのいずれかで指定します。デフォルトのプリフィックスディレクトリーは APIcast である点に注意してください。

APICAST_LOG_LEVEL

値: debug | info | notice | warn | error | crit | alert | emerg

デフォルト: warn

OpenResty ログのログレベルを指定します。

APICAST_ACCESS_LOG_FILE

デフォルト: stdout

アクセスログを保存するファイルを定義します。

APICAST_OIDC_LOG_LEVEL

値: debug | info | notice | warn | error | crit | alert | emerg

デフォルト: err

OpenID Connect インテグレーションに関するログのログレベルを設定することができます。

APICAST_MANAGEMENT_API

値:

  • disabled: 完全に無効で、ポートをリッスンするだけの状態
  • status: ヘルスチェック用に、/status/ エンドポイントだけが有効な状態
  • debug: API 全体がオープンな状態

Management API の機能は強力で、APIcast の設定を制御することができます。debug レベルは、デバッグ用途にのみ有効にしてください。

APICAST_MODULE

デフォルト: apicast

非推奨: この環境変数の代わりに、policies を使用してください。

API ゲートウェイロジックを実装するメインの Lua モジュール名を指定します。カスタムモジュールは、デフォルトの apicast.lua モジュールの機能に優先します。モジュールの使用方法の 例 を参照してください。

APICAST_PATH_ROUTING

値:

  • 真の場合には true または 1
  • 偽の場合には false、0、または空欄

このパラメーターを true に設定すると、ゲートウェイはデフォルトのホストベースのルーティングに加えて、パスベースのルーティングを使用します。API リクエストは、リクエストの Host ヘッダーの値が Public Base URL にマッチするサービスの中で、マッピングルールが最初にマッチするサービスにルーティングされます。

APICAST_POLICY_LOAD_PATH

デフォルト: APICAST_DIR/policies

値: 文字列[:]

例: ~/apicast/policies:$PWD/policies

APIcast がポリシーを探すパスのコロン (:) 区切りリスト。開発用ディレクトリーから最初にポリシーを読み込む場合や、例を読み込む場合に使用することができます。

APICAST_PROXY_HTTPS_CERTIFICATE_KEY

デフォルト:

値: 文字列

例: /home/apicast/my_certificate.key

クライアント SSL 証明書の鍵へのパス

APICAST_PROXY_HTTPS_CERTIFICATE

デフォルト:

値: 文字列

例: /home/apicast/my_certificate.crt

APIcast がアップストリームと接続する際に使用するクライアント SSL 証明書へのパス。この証明書が設定内のすべてのサービスに使用される点に注意してください。

APICAST_PROXY_HTTPS_PASSWORD_FILE

デフォルト:

値: 文字列

例: /home/apicast/passwords.txt

APICAST_PROXY_HTTPS_CERTIFICATE_KEY で指定する SSL 証明書の鍵のパスフレーズが含まれるファイルへのパス

APICAST_PROXY_HTTPS_SESSION_REUSE

デフォルト: on

値:

  • on: SSL セッションを再利用します。
  • off: SSL セッションを再利用しません。

APICAST_HTTPS_VERIFY_DEPTH

デフォルト: 1

値: 正の整数

クライアント証明書チェーンの最大長を定義します。このパラメーターの値が 1 の場合には、チェーンに 1 つの追加証明書 (たとえば 中間 CA) が含まれる可能性があることを意味します。

APICAST_REPORTING_THREADS

デフォルト: 0

値: 0 または正の整数

実験的機能: 負荷が極端に大きい場合のパフォーマンスは予測が不可能で、レポートが失われる可能性があります。

0 より大きい値を設定すると、バックエンドへの非同期のレポートが有効になります。これは、パフォーマンスを向上させるための新たな 実験的 機能です。クライアントにはバックエンドのレイテンシーは適用されず、すべてが非同期状態で処理されます。この値により、同時に実行することのできる非同期レポートの数を決定します。レポート数がこの値を超えると、クライアントにスロットリングが適用され、レイテンシーが追加されます。

APICAST_RESPONSE_CODES

値:

  • 真の場合には true または 1
  • 偽の場合には false、0、または空欄

デフォルト: 空欄 (false)

true に設定すると、APIcast は API バックエンドから返されたレスポンスのレスポンスコードを 3scale に記録します。レスポンスコード機能の詳細は、3scale カスタマーポータル を参照してください。

APICAST_SERVICES_LIST_URL

値: .*.example.com 等の PCRE (Perl 互換正規表現)

3scale API Manager で設定されているサービスにフィルターを適用します。

このフィルターは、公開ベース URL を照合します。フィルターにマッチしないサービスは、無視されます。正規表現をコンパイルすることができない場合には、サービスは読み込まれません。

注記

サービスが一致しないが APICAST_SERVICES_LIST に 含まれている 場合、そのサービスは破棄されません。

例6.1 例を示します。

正規表現フィルター http://.*.foo.dev が以下のバックエンドのエンドポイントに適用される。

  1. http://staging.foo.dev
  2. http://staging.bar.dev
  3. http://prod.foo.dev
  4. http://prod.bar.dev

この場合、1 および 3 は Embedded APIcast に設定され、2 および 4 は無視されます。

APICAST_SERVICES_LIST

値: サービス ID のコンマ区切りリスト

APICAST_SERVICES_LIST 環境変数を使用して、3scale API Manager で設定されているサービスにフィルターを適用します。この環境変数は、ゲートウェイの特定サービスの設定にだけ適用され、リストで指定されていないサービス ID は無視されます。プロダクトのサービス識別子は、管理ポータルの Products > [Your_product_name] > Overview に移動し、続いて、Configuration, Methods and Settings および ID for API calls を参照して確認することができます。

APICAST_SERVICE_${ID}_CONFIGURATION_VERSION

${ID} を実際のサービス ID に置き換えてください。値は、管理ポータルの設定履歴に表示される設定バージョンにする必要があります。特定のバージョンに設定すると自動更新されなくなり、常にそのバージョンが使用されます。

APICAST_WORKERS

デフォルト: auto

値: 数字 | auto

この値は、nginx の worker_processes ディレクティブ で使用されます。1 が使用される開発環境を除き、デフォルトの APIcast では auto が使用されます。

BACKEND_ENDPOINT_OVERRIDE

設定からのバックエンドエンドポイントをオーバーライドする URI。OpenShift がデプロイした AMP の外部にデプロイする際に役立ちます。例: https://backend.example.com。

OPENSSL_VERIFY

値:

  • 0、false: ピア検証を無効にします
  • 1、true: ピア検証を有効にします

OpenSSL ピア検証を制御します。OpenSSL はシステム証明書ストアを使用することができないため、デフォルトではオフになっています。カスタム証明書バンドルを信頼済み証明書に追加する必要があります。

lua_ssl_trusted_certificate を使用して、export-builtin-trusted-certs により生成される証明書バンドルをポイントすることを推奨します。

RESOLVER

OpenResty で使用されるカスタム DNS リゾルバーを指定することができます。RESOLVER パラメーターが空欄の場合には、DNS リゾルバーは自動検出されます。

THREESCALE_CONFIG_FILE

ゲートウェイの設定が含まれる JSON ファイルへのパス。ゲートウェイが正常に動作するには、THREESCALE_PORTAL_ENDPOINT または THREESCALE_CONFIG_FILE のどちらかを指定する必要があります。これら 2 つの環境変数のうち、THREESCALE_CONFIG_FILE が優先されます。

Proxy Config Show および Proxy Config Show Latest エンドポイントは、サービスによって範囲が限定され、Proxy Configs List サービスも対象となります。サービスの ID を知っている必要があります。以下のオプションを使用します。

  • Proxy Configs List プロバイダーエンドポイントを使用します: <schema>://<admin-portal-domain>/admin/api/account/proxy_configs/<env>.json

    • エンドポイントは、各サービスの最新のものだけでなく、プロバイダーの保存されているすべてのプロキシー設定を返します。JSON で返された proxy_configs の配列を繰り返し処理し、同じ proxy_config.content.id (サービスの ID) を持つすべてのプロキシー設定の中で proxy_config.version が最も高い proxy_config.content を選択します。

  • Service List エンドポイントの使用: /admin/api/services.json

    • エンドポイントには、プロバイダーのすべてのサービスが一覧表示されます。サービスの配列を繰り返し処理し、サービスごとに、サービスによってスコープが設定された Proxy Config Show Latest エンドポイントを消費します。

コンテナーイメージを使用してゲートウェイをデプロイする場合:

  1. イメージへのファイルを読み取り専用ボリュームとして設定します。
  2. ボリュームをマウントした場所を示すパスを指定します。

設定ファイルの例については、examples フォルダーを参照してください。

THREESCALE_DEPLOYMENT_ENV

値: staging | production

デフォルト: production

この環境変数の値を使用して、新しい APIcast を使用する際に設定をダウンロードする環境 (3scale ステージングまたは実稼働環境) を定義します。

この値は、3scale Service Management API への承認/レポートリクエストのヘッダー X-3scale-User-Agent でも使用されます。この値は、3scale では統計のためだけに使用されます。

THREESCALE_PORTAL_ENDPOINT

パスワードおよびポータルエンドポイントが含まれる、以下の形式の URI。

<schema>://<password>@<admin-portal-domain>

ここで、

  • <password> は、プロバイダーキーまたは 3scale Account Management API のアクセストークンのいずれかです。
  • <admin-portal-domain> は、3scale 管理ポータルにログインするための URL アドレスです。

例: https://access-token@account-admin.3scale.net

THREESCALE_PORTAL_ENDPOINT 環境変数を指定すると、ゲートウェイは初期化時に 3scale から設定をダウンロードします。この設定には、API の Integration ページで指定したすべての設定が含まれます。

ゲートウェイが正常に動作するには、THREESCALE_PORTAL_ENDPOINT または THREESCALE_CONFIG_FILE (優先) を指定する 必要があります。

OPENTRACING_TRACER

例: jaeger

この環境変数は、読み込むトレースライブラリーを制御します。現時点では、OpenTracing のトレーサーとして利用可能なのは jaeger だけです。

空欄の場合には、OpenTracing のサポートは無効です。

OPENTRACING_CONFIG

この環境変数は、OpenTracing トレーサーの設定ファイルを定義するのに使用されます。OPENTRACING_TRACER が設定されていない場合には、この変数は無視されます。

それぞれのトレーサーには、デフォルトの設定ファイル * jaeger: conf.d/opentracing/jaeger.example.json があります。

この変数を使用してファイルパスを設定することにより、デフォルトで提供されるものとは異なる設定をマウントすることができます。

例: /tmp/jaeger/jaeger.json

OPENTRACING_HEADER_FORWARD

デフォルト: uber-trace-id

この環境変数は、OpenTracing の情報を転送するのに使用される HTTP ヘッダーを制御します。この HTTP ヘッダーは、アップストリームサーバーに転送されます。

APICAST_HTTPS_PORT

デフォルト: 値なし

HTTPS 接続用に APIcast がリッスンを開始するポートを制御します。この設定が HTTP 用ポートと競合する場合には、HTTPS 用にだけ使用されます。

APICAST_HTTPS_CERTIFICATE

デフォルト: 値なし

HTTPS 接続用 X.509 証明書が含まれる PEM 形式ファイルへのパス

APICAST_HTTPS_CERTIFICATE_KEY

デフォルト: 値なし

X.509 証明書の秘密鍵が含まれる PEM 形式ファイルへのパス

all_proxy、ALL_PROXY

デフォルト: 値なし 値: 文字列 例: http://forward-proxy:80

プロトコル固有のプロキシーが指定されていない場合に、サービスへの接続に使用される HTTP プロキシーを定義します。認証機能はサポートされていません。

http_proxy、HTTP_PROXY

デフォルト: 値なし 値: 文字列 例: http://forward-proxy:80

HTTP サービスへの接続に使用される HTTP プロキシーを定義します。認証機能はサポートされていません。

https_proxy、HTTPS_PROXY

デフォルト: 値なし 値: 文字列 例: https://forward-proxy:443

HTTPS サービスへの接続に使用される HTTP プロキシーを定義します。認証機能はサポートされていません。

no_proxy、NO_PROXY

デフォルト: 値なし 値: string\[,<string>\]; * 例: foo,bar.com,.extra.dot.com

リクエストをプロキシーすべきではないホスト名およびドメイン名のコンマ区切りリストを定義します。* 1 文字 (すべてのホストとマッチする) を設定すると、実質的にプロキシーは無効になります。

トップに戻る
Red Hat logoGithubredditYoutubeTwitter

詳細情報

試用、購入および販売

コミュニティー

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

Red Hat をお使いのお客様が、信頼できるコンテンツが含まれている製品やサービスを活用することで、イノベーションを行い、目標を達成できるようにします。 最新の更新を見る.

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

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。このような変更は、段階的に実施される予定です。詳細情報: Red Hat ブログ.

会社概要

Red Hat は、企業がコアとなるデータセンターからネットワークエッジに至るまで、各種プラットフォームや環境全体で作業を簡素化できるように、強化されたソリューションを提供しています。

Theme

© 2025 Red Hat