第6章 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_EXTENDED_METRICS

デフォルト: false

値: ブール値

例:true

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

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

値:

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

APICAST_MODULE

デフォルト: apicast

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

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

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

値:

APICAST_HTTPS_VERIFY_DEPTH

デフォルト: 1

値: 正の整数

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

APICAST_REPORTING_THREADS

デフォルト: 0

値: 0 または正の整数

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

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

APICAST_RESPONSE_CODES

値:

デフォルト: 空欄 (false)

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

APICAST_SERVICES_FILTER_BY_URL

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

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

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

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

値:

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

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

設定ファイルの例については、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 (優先) を指定する 必要があります。

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 文字 (すべてのホストとマッチする) を設定すると、実質的にプロキシーは無効になります。