第7章 APIcast の環境変数

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

all_proxy、ALL_PROXY

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

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

APICAST_ACCESS_LOG_FILE

デフォルト: stdout

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

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_EXTENDED_METRICS

デフォルト: false

値: ブール値

例:「true」

Prometheus メトリクスに関する追加情報を有効にします。以下のメトリクスでは service_id および service_system_name ラベルを使用することができ、APIcast をより詳細に設定することができます。

APICAST_HTTPS_CERTIFICATE

デフォルト: 値なし

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

APICAST_HTTPS_CERTIFICATE_KEY

デフォルト: 値なし

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

APICAST_HTTPS_PORT

デフォルト: 値なし

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

APICAST_HTTPS_VERIFY_DEPTH

デフォルト: 1

値: 正の整数

クライアント証明書チェーンの最大長を定義します。このパラメーターの値が 1 の場合は、クライアント証明書チェーンに追加の証明書を含めることができます。たとえば、ルート認証局などです。

APICAST_LOAD_SERVICES_WHEN_NEEDED

値:

デフォルト: false

多くのサービスが設定されている場合に、このオプションを使用することができます。ただし、そのパフォーマンスは、サービスの数、APIcast と 3scale 管理ポータル間のレイテンシー、設定の残存期間 (TTL) など、他の要素に依存します。

デフォルトでは、APIcast が管理ポータルから設定をダウンロードするたびに、すべてのサービスが読み込みます。このオプションを有効にすると、設定にレイジーローディングが使用されます。APIcast は、リクエストの Host ヘッダーで指定したホストに設定されたサービスだけを読み込みます。

APICAST_LOG_FILE

デフォルト: stderr

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

APICAST_LOG_LEVEL

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

デフォルト: warn

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

APICAST_MANAGEMENT_API

値:

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

APICAST_MODULE

デフォルト: apicast

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

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

APICAST_OIDC_LOG_LEVEL

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

デフォルト: err

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

APICAST_PATH_ROUTING

値:

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

APICAST_PATH_ROUTING_ONLY

値:

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

このパラメーターは、APICAST_PATH_ROUTING に優先します。APICAST_PATH_ROUTING_ONLY が有効になっている場合、APIcast は APICAST_PATH_ROUTING の値にかかわらず、パスベースのルーティングだけを行います。

APICAST_POLICY_LOAD_PATH

デフォルト: APICAST_DIR/policies

値: 文字列[:]

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

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

APICAST_PROXY_HTTPS_CERTIFICATE

デフォルト:

値: 文字列

例: /home/apicast/my_certificate.crt

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

APICAST_PROXY_HTTPS_CERTIFICATE_KEY

デフォルト:

値: 文字列

例: /home/apicast/my_certificate.key

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

APICAST_PROXY_HTTPS_PASSWORD_FILE

デフォルト:

値: 文字列

例: /home/apicast/passwords.txt

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

APICAST_PROXY_HTTPS_SESSION_REUSE

デフォルト: on

値:

APICAST_REPORTING_THREADS

デフォルト: 0

値: 0 または正の整数

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

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

APICAST_RESPONSE_CODES

値:

デフォルト: 空欄 (false)

True に設定すると 、 APIcast は API バックエンドによって返されるレスポンスのレスポンスコードを 3scale に記録します。3scale カスタマーポータルで レスポンスコード機能の詳細を確認してください。

APICAST_SERVICE_${ID}_CONFIGURATION_VERSION

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

APICAST_SERVICES_LIST

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

APICAST_SERVICES_LIST 環境変数は、3scale API Manager で設定したサービスにフィルターするために使用されます。これにより、ゲートウェイ内の特定サービスの設定にのみ適用され、リストで指定されていないサービス識別子を破棄します。プロダクトのサービス識別子は、Products > [Your_product_name] > Overview の順に移動し、Configuration、Methods and Settings、 および API calls の ID を参照してください。

APICAST_SERVICES_FILTER_BY_URL

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

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

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

APICAST_UPSTREAM_RETRY_CASES

値: error | timeout | invalid_header | http_500 | http_502 | http_503 | http_504 | http_403 | http_404 | http_429 | non_idempotent | off

APICAST_WORKERS

デフォルト: auto

値: 数字 | auto

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

BACKEND_ENDPOINT_OVERRIDE

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

HTTP_KEEPALIVE_TIMEOUT

デフォルト: 75 値: 正の整数 例: 1

このパラメーターにより、キープアライブ用のクライアント接続がタイムアウトする期間を設定します。この間、サーバー側では接続が開き続けます。値にゼロを設定すると、キープアライブ用のクライアント接続は無効になります。

デフォルトでは、ゲートウェイは HTTP_KEEPALIVE_TIMEOUT を無効にした状態に維持します。この設定により、NGINX からのキープアライブのタイムアウト (デフォルト値は 75 秒) を使用することができます。

http_proxy、HTTP_PROXY

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

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

https_proxy、HTTPS_PROXY

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

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

no_proxy、NO_PROXY

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

OPENSSL_VERIFY

値:

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

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

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 ヘッダーは、アップストリームサーバーに転送されます。

OPENTRACING_TRACER

例: jaeger

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

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

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 を知っている必要があります。以下のオプションを使用します。

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

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

THREESCALE_DEPLOYMENT_ENV

値: staging | production

デフォルト: production

この環境変数の値により、設定のダウンロード元である環境が定義されます。これは、新しい APIcast を使用する際に 3scale ステージングまたは実稼働環境のいずれかになります。

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

THREESCALE_PORTAL_ENDPOINT

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

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

ここでは、以下のようになります。

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

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

この環境変数を使用して、マスター管理ポータルを使用して単一のゲートウェイを作成する こともできます。

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