環境変数

デプロイ時に環境変数を設定しておくことで、Kompira の動作環境を指定することが出来ます。 以下では各構成で共通的な環境変数について示します。 各構成で独自の環境変数が定義されている場合もありますので、それぞれの説明を参照してください。

HOSTNAME

デプロイする各コンテナには、ホストサーバのホスト名をベースにしたホスト名を内部的に付与するようにしています。 そのため、デプロイ時にホストサーバのホスト名を環境変数 HOSTNAME で参照しています。

環境変数 HOSTNAME でホストサーバのホスト名を参照できない環境の場合は、デプロイ前に環境変数 HOSTNAME を設定するようにしてください。

KOMPIRA_IMAGE_NAME / KOMPIRA_IMAGE_TAG

デプロイする Kompira コンテナのイメージとタグを指定します。 独自に用意したコンテナイメージや、特定のバージョンのコンテナイメージを利用したい場合にこの環境変数で指定することができます。

KOMPIRA_IMAGE_TAG のデフォルト値は ke2-docker 更新時点で公開されていた最新の kompira コンテナイメージを示しています（例えば "2.0.2" など）。KOMPIRA_IMAGE_TAG に "latest" と指定すると、デプロイ時に公開されている最新の kompira コンテナイメージを利用することができます。

DATABASE_URL / AMQP_URL / CACHE_URL

Kompira に必要なサブシステムである、データベースやメッセージキューおよびキャッシュへの接続先を URL 形式で指定します。 デフォルト値ではそれぞれ以下のように接続します。

• データベース: 同じサーバ上の PostgreSQL に Unix ドメインソケットで接続します。
• メッセージキュー: 同じサーバ上の RabbitMQ に TCP 接続します。
• キャッシュ: 同じサーバ上の Redis に TCP 接続します。

参考: https://django-environ.readthedocs.io/en/latest/types.html#environ-env-db-url

TZ / LANGUAGE_CODE

各コンテナのタイムゾーンと言語コードを設定します。

• タイムゾーンは、画面やログで表示される時刻のタイムゾーンの指定になります。
• 言語コードは "ja" (日本語) または "en" (英語) が指定できます。この値は、初回起動時にインポートする初期データの言語の指定になります。

MAX_EXECUTOR_NUM

Kompira エンジン (kengine) 上で動作する Executor プロセスの最大数を、1 つの kengine あたりで指定します。未設定または 0 の場合は、その kengine コンテナの CPU コア数に従います。明示的に上限を指定する場合は 1 以上の整数を指定してください。

1 つの kengine が起動する Executor 数は、その kengine の CPU コア数 (本値を指定した場合は CPU コア数と本値の小さい方) までです。さらに、システム全体で動作する Executor の合計数は、導入されているライセンスで付与される最大 Executor 数に制限されます。複数の kengine を動作させる構成 (Swarm など) では、各 kengine への割り当ては起動時にシステム全体の残り枠から配分されます。

ジョブフローの並列実行数を増やしてスケールしたい場合は、ライセンスの購入とサーバリソース (CPU コア数・ノード) の増強で対応します。なお各 Executor は PostgreSQL への接続を 1 つ保持するため、Executor 数を増やす構成では接続先 PostgreSQL の最大接続数 (内部 postgres 構成では POSTGRES_MAX_CONNECTIONS、外部データベース構成では接続先 DB サーバ側で設定) の見積りにも反映してください。

KOMPIRA_LOG_DIR

ログを保存する ホスト側のディレクトリ を指定します。指定するとコンテナ内の /var/log/kompira にバインドマウントされます。未指定の場合は、標準シングル構成・外部DBシングル構成では名前付きボリューム kompira_log に、Swarm 構成では共有ディレクトリ (SHARED_DIR) 配下の log ディレクトリに保存されます。(コンテナ内のログ出力パス自体は下記 LOGGING_DIR で指定します。)

LOGGING_XXX / AUDIT_LOGGING_XXX

Kompira コンテナイメージにおけるプロセスログおよび監査ログの設定について指定します。

• LOGGING_LEVEL: プロセスログの記録レベルを指定します。
  • デフォルトは "INFO" です。
• AUDIT_LOGGING_LEVEL: 監査ログの記録レベルを指定します。
  • デフォルトは 2 です。
• LOGGING_DIR / AUDIT_LOGGING_DIR: ログの出力先ディレクトリを指定します。
  • デフォルトは "/var/log/kompira" です。標準的なデプロイ手順ではこのディレクトリはホストの kompira_log ボリュームにマウントされます。
  • デフォルト (/var/log/kompira) から変更する場合は、変更先の出力ディレクトリがコンテナから書き込める形で用意されていることを確認してください。
• LOGGING_BACKUP: ログローテート時に保存されるバックアップ数を指定します。
  • LOGGING_BACKUP のデフォルトは 7 です。
  • AUDIT_LOGGING_BACKUP のデフォルトは 365 です。
• LOGGING_WHEN / AUDIT_LOGGING_WHEN: ログローテートのタイミングを指定します。デフォルトは "MIDNIGHT" です。
• LOGGING_INTERVAL / AUDIT_LOGGING_INTERVAL: ログローテートのインターバルを指定します。デフォルトは 1 です。

ログのローテーションは LOGGING_WHEN および LOGGING_INTERVAL の積に基づいて行います。 LOGGING_WHEN は LOGGING_INTERVAL の単位を指定するために使います。使える値は下表の通りです。大小文字の区別は行いません。

UWSGI_XXX / KOMPIRA_NGINX_UWSGI_READ_TIMEOUT / KOMPIRA_NGINX_UWSGI_SEND_TIMEOUT

Kompira コンテナで動作する uWSGI (アプリケーションサーバ) のワーカ並列度・タイムアウトと、その前段の nginx から uWSGI へのタイムアウトを指定します。 いずれも未設定なら従来どおりのデフォルト値で動作するため、通常はそのままで構いません。

これらのパラメータは、目的別に (1) 同時処理数 (並列度)、(2) タイムアウト、(3) 接続の受け付け の 3 系統に分かれます。まず一覧を示し、続いて調整が必要になる場面ごとの指針を示します。

uWSGI 系パラメータを調整すべき代表的な場面と対応は次のとおりです。

(1) 同時処理数を上げたい — 高負荷で画面や API の応答が全体的に遅い、あるいはジョブフローの .wait / .recv を画面/API (HTTP) 経由で多用してワーカが長時間占有される場合。

• 同時に処理できるリクエスト数は UWSGI_PROCESSES × UWSGI_THREADS です。CPU を使い切る処理はプロセス数を、.wait / .recv のような待ち中心の処理はスレッド数を増やすのが基本です。
• スレッドを増やす場合は UWSGI_THUNDER_LOCK を true にすることを推奨します。デフォルト (false) では新規接続時に複数ワーカが一斉に起きて処理が一部に偏る (thundering herd) ことがあり、スレッドを増やしても性能が伸びにくくなります。有効化すると accept が直列化され、各ワーカへ接続が公平に配分されます。

注意 (POSTGRES_MAX_CONNECTIONS の見積り): DB 接続数はおおむね「処理中の Web リクエスト数 (同時上限 = UWSGI_PROCESSES × UWSGI_THREADS。アイドル時はほぼ 0) ＋ kengine (エンジン本体 + Executor 数。1 Executor = 1 接続で、並行ジョブフロー数では増えません) ＋ 管理・保守用のわずかな接続」です。実機検証では、同時 K 件のブロッキング要求 (.wait / .recv 等) を捌くには POSTGRES_MAX_CONNECTIONS ≧ K + 約 15 が目安です。デフォルト 100 は標準構成には十分ですが、UWSGI_PROCESSES × UWSGI_THREADS を大きく上げる場合は連動して引き上げてください。不足すると "FATAL: sorry, too many clients already" で接続が拒否され、画面や API が 500 エラーになります。(外部データベース構成では POSTGRES_MAX_CONNECTIONS 環境変数は無効なので、接続先 DB サーバの max_connections で同様に見積もってください。)

(2) 個々のリクエストの処理が長い — 大きなエクスポート・重いクエリ・HTTP 経由の長い .wait / .recv など、1 リクエストの処理に時間がかかる場合。

• 途中で打ち切られないよう KOMPIRA_NGINX_UWSGI_READ_TIMEOUT / KOMPIRA_NGINX_UWSGI_SEND_TIMEOUT (各デフォルト 300 秒) を想定する最長リクエスト時間以上に延ばします。逆に、枯渇時に早期に失敗させたい場合は短めにします。
• UWSGI_HARAKIRI はデフォルトで無効です。有効化すると全 HTTP リクエストが対象になり、この秒数を超えたリクエストはワーカごと強制終了・再起動されます。有効化する場合は、想定最長時間かつ KOMPIRA_NGINX_UWSGI_READ_TIMEOUT / KOMPIRA_NGINX_UWSGI_SEND_TIMEOUT の長い方以上の値にしてください。

メモ: UWSGI_HARAKIRI と nginx のタイムアウトは役割が異なります。UWSGI_HARAKIRI は張り付いたリクエストを打ち切って ワーカを回収 するためのもの (処理時間のハードリミット)、nginx の read/send タイムアウトは応答しない upstream を待ち続けず クライアントにエラーを返す ためのもの (I/O 間の無通信時間) です。ワーカ枯渇の緩和は (1) の並列度引き上げが基本で、UWSGI_HARAKIRI は想定を超えて張り付いたリクエストに対する安全網として使います。

(3) 短時間に大量の接続が集中する — バースト的なアクセスで接続が待たされる／拒否される場合。

• UWSGI_LISTEN (接続待ち行列 = listen backlog の長さ) を増やします。待ち行列を超えて到着した接続は待たされたり失敗したりします。実効値はカーネルの net.core.somaxconn が上限となります (KE2.0 のコンテナデフォルトは 4096)。

POSTGRES_XXX

postgres コンテナの主要なチューニング項目を指定します。 いずれも未設定なら PostgreSQL の標準値で動作するため、通常はそのままで構いません。 上記の Web ワーカ並列度を引き上げる場合や、大規模環境でメモリを活用したい場合に調整します。

なお、これらは内部 postgres コンテナを持つ標準シングル構成でのみ有効です。 外部データベース構成 (single/extdb・cluster/swarm) では効果がなく、 チューニングは接続先の外部 DB サーバ側で行ってください。

• POSTGRES_MAX_CONNECTIONS: 受け付ける最大同時接続数です。上記の Web ワーカ並列度と連動させて設定します。
• POSTGRES_SHARED_BUFFERS / POSTGRES_EFFECTIVE_CACHE_SIZE / POSTGRES_WORK_MEM / POSTGRES_MAINTENANCE_WORK_MEM はメモリ関連のチューニングパラメータです。いずれもホストの搭載メモリを基準に決める値で、特に POSTGRES_EFFECTIVE_CACHE_SIZE のデフォルト "4GB" は一定以上の搭載メモリを前提とするため、小規模なホストや他コンテナが同居する構成では実メモリに合わせて見直してください。
• POSTGRES_WORK_MEM はクエリのソート/ハッシュ処理ごとに確保されるため、実効的なメモリ使用量はおおよそ POSTGRES_WORK_MEM × 同時接続数 × クエリ内の並行ソート数まで膨らみます。POSTGRES_WORK_MEM と POSTGRES_MAX_CONNECTIONS を同時に引き上げる際はホストの空きメモリに注意してください。
• 各パラメータの詳細は PostgreSQL のドキュメントを参照してください。