第7章 APIcast の環境変数

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

all_proxy、ALL_PROXY

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

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

APICAST_ACCESS_LOG_BUFFER

デフォルト: 値なし

値: 正の整数

アクセスログ書き込みをバイトのチャンクに含めることを許可します。その結果、システムコールが少なくなり、ゲートウェイのパフォーマンスが向上します。

APICAST_ACCESS_LOG_FILE

デフォルト: stdout

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

APICAST_BACKEND_CACHE_HANDLER

値: strict | resilient

デフォルト: strict

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

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

APICAST_CACHE_MAX_TIME

デフォルト: 1m

値: 文字列

レスポンスがシステムにキャッシュされる設定の場合、この変数の値はキャッシュされる最大の時間を示します。cache-control ヘッダーが設定されていない場合、キャッシュされる時間はここで定義される時間になります。

この値のフォーマットは、proxy_cache_valid NGINX ディレクティブ で定義されます。

このパラメーターは、コンテンツキャッシュポリシーを使用している API によってのみ使用され、リクエストのキャッシュが可能です。

APICAST_CACHE_STATUS_CODES

デフォルト: 200、302

値: 文字列

アップストリームからのレスポンスコードがこの環境変数で定義されるステータスコードのいずれかと一致する場合、レスポンスの内容が NGINX にキャッシュされます。キャッシュされる時間は、ヘッダーキャッシュ時間の値または APICAST_CACHE_MAX_TIME 環境変数で定義される最大時間のいずれかに依存します。

このパラメーターは、コンテンツキャッシュポリシーを使用している API によってのみ使用され、リクエストのキャッシュが可能です。

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 ヘッダーの値が 公開ベース 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 に記録します。詳細は、Setting up and evaluating the 3scale response codes log for your APIを参照してください。

APICAST_SERVICE_CACHE_SIZE

値: 0 または正の整数

デフォルト: 1000

APIcast が内部キャッシュに保存することのできるサービスの数を指定します。Lua の lru キャッシュによりすべてのエントリーが初期化されるので、大きな値を設定するとパフォーマンスに影響が出ます。

APICAST_SERVICE_${ID}_CONFIGURATION_VERSION

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

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_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

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

リクエストをプロキシーすべきではないホスト名およびドメイン名のコンマ区切りリストを定義します。* 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 が優先されます。

ゲートウェイの設定が含まれるファイルをビルドする方法は、サービスの数により 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>

ここで、

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

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

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

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