Merge pull request #54 from fixpoint/feature/improve-environment-sett…

…ings

Feature/improve environment settings

ChangeLog

@@ -1,3 +1,13 @@
+2024-09-02  Ichiro TAKAHASHI  <[email protected]>
+
+	* ログ設定 (LOGGING_XXX, AUDIT_LOGGING_XXX) を環境変数で指定できるようにしました。(#54)
+
+	* 最大エグゼキュータ数 (MAX_EXECUTOR_NUM) を環境変数で指定できるようにしました。(#54)
+
+	* 環境変数 HOSTNAME が指定されていない場合はエラーになるようにしました。(#54)
+
+	* 環境変数の説明を Environment.md に独立させました。(#54)
+
 2024-08-27  Hasan Mahamudul  <[email protected]>
 
 	* rabbimq の cluster_partition_handling 設定を pause_minority に更新しました。(#50)

Environment.md

@@ -0,0 +1,95 @@
+# 環境変数
+
+デプロイ時に環境変数を設定しておくことで、Kompira の動作環境を指定することが出来ます。
+以下では各構成で共通的な環境変数について示します。
+各構成で独自の環境変数が定義されている場合もありますので、それぞれの説明を参照してください。
+
+| 環境変数名            | デフォルト                                          | 意味                       |
+|-----------------------|-----------------------------------------------------|----------------------------|
+| `HOSTNAME`            | (下記参照)                                          | ホスト名                   |
+| `KOMPIRA_IMAGE_NAME`  | "kompira.azurecr.io/kompira-enterprise"             | Kompira イメージ           |
+| `KOMPIRA_IMAGE_TAG`   | "latest"                                            | Kompira タグ               |
+| `DATABASE_URL`        | "pgsql://kompira@//var/run/postgresql/kompira"      | データベースの接続先       |
+| `AMQP_URL`            | "amqp://guest:guest@localhost:5672"                 | メッセージキューの接続先   |
+| `CACHE_URL`           | "redis://localhost:6379"                            | キャッシュの接続先         |
+| `TZ`                  | "Asia/Tokyo"                                        | タイムゾーン               |
+| `LANGUAGE_CODE`       | "ja"                                                | 言語設定                   |
+| `MAX_EXECUTOR_NUM`    | "0"                                                 | Executor の最大数          |
+| `LOGGING_XXX`         | (下記参照)                                          | プロセスログの設定         |
+| `AUDIT_LOGGING_XXX`   | (下記参照)                                          | 監査ログの設定             |
+
+## HOSTNAME
+
+デプロイする各コンテナには、ホストサーバのホスト名をベースにしたホスト名を内部的に付与するようにしています。
+そのため、デプロイ時にホストサーバのホスト名を環境変数 `HOSTNAME` で参照しています。
+
+環境変数 `HOSTNAME` でホストサーバのホスト名を参照できない環境の場合は、デプロイ前に環境変数 `HOSTNAME` を設定するようにしてください。
+
+## KOMPIRA_IMAGE_NAME / KOMPIRA_IMAGE_TAG
+
+デプロイする 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 エンジン上で動作する Executor プロセスの最大数を指定します。
+未設定または 0 を指定した場合は kengine コンテナの CPUコア数だけ Executor プロセスを起動します。
+なお、MAX_EXECUTOR_NUM を CPU コア数より多くしても、実行する Executor プロセス数は CPU コア数で抑えられます。
+
+    プロセス数＝min(CPUコア数、MAX_EXECUTOR_NUM)
+
+また、導入されているライセンスによっても実際に動作する Executor のプロセス数は制限されます。
+
+## LOGGING_XXX / AUDIT_LOGGING_XXX
+
+Kompira コンテナイメージにおけるプロセスログおよび監査ログの設定について指定します。
+
+| 環境変数名(プロセスログ) | 環境変数名(監査ログ)    | 意味                        |
+|--------------------------|-------------------------|-----------------------------|
+| LOGGING_LEVEL            | AUDIT_LOGGING_LEVEL     | ログレベル                  |
+| LOGGING_DIR              | AUDIT_LOGGING_DIR       | ログ出力ディレクトリ        |
+| LOGGING_BACKUP           | AUDIT_LOGGING_BACKUP    | ログバックアップ数          |
+| LOGGING_WHEN             | AUDIT_LOGGING_WHEN      | ログローテートタイミング    |
+| LOGGING_INTERVAL         | AUDIT_LOGGING_INTERVAL  | ログローテートインターバル  |
+
+- `LOGGING_LEVEL`: プロセスログの記録レベルを指定します。
+    - デフォルトは "INFO" です。
+- `AUDIT_LOGGING_LEVEL`: 監査ログの記録レベルを指定します。
+    - デフォルトは 2 です。
+- `LOGGING_DIR` / `AUDIT_LOGGING_DIR`: ログの出力先ディレクトリを指定します。
+    - デフォルトは "/var/log/kompira" です。標準的なデプロイ手順ではこのディレクトリはホストの kompira_log ボリュームにマウントされます。
+- `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` の単位を指定するために使います。使える値は下表の通りです。大小文字の区別は行いません。
+
+| LOGGING_WHEN の値   | LOGGING_INTERVAL の単位   |
+|---------------------|---------------------------|
+| "S"                 | 秒                        |
+| "M"                 | 分                        |
+| "H"                 | 時間                      |
+| "D"                 | 日                        |
+| "W0"-"W6"           | 曜日 (0=月曜)             |
+| "MIDNIGHT"          | 深夜0時                   |

README.md

@@ -64,16 +64,8 @@ $ sudo systemctl enable --now docker
 ### 4.2. 環境変数の設定
 
 デプロイ時に環境変数を設定しておくことで、Kompira の動作環境を指定することが出来ます。
-以下では各構成で共通的な環境変数について示します。
-各構成で独自の環境変数が定義されている場合もありますのでそれぞれの README.md を参照してください。
 
-
-| 環境変数                | 意味                        | デフォルト値                            | 備考                                                   |
-| ----------------------- | --------------------------- | --------------------------------------- | ------------------------------------------------------ |
-| `TZ`                    | タイムゾーン                | "Asia/Tokyo"                            | 画面やログで表示される時刻のタイムゾーンを指定します   |
-| `LANGUAGE_CODE`         | 言語コード ("ja" or "en")   | "ja"                                    | 初回起動時にインポートする初期データの言語を指定します |
-| `KOMPIRA_IMAGE_NAME`    | Kompira イメージ            | "kompira.azurecr.io/kompira-enterprise" | デプロイする Kompira コンテナのイメージを指定します    |
-| `KOMPIRA_IMAGE_TAG`     | Kompira タグ                | "latest"                                | デプロイする Kompira コンテナのタグを指定します        |
+指定できる環境変数の詳細については [環境変数](./Environment.md) を参照してください。
 
 ## 5. Kompira ライセンス
 
@@ -85,10 +77,14 @@ Kompira の使用には、ライセンス登録が必要です。詳しくは [l
 
 ## 6. Kompira 関連の情報
 
-### 6.1. Kompira 運用自動化コラム
+### 6.1. KE2.0 管理者マニュアル
+
+KE2.0 のデプロイ手順などの管理手順については [KE2.0管理者マニュアル](https://fixpoint.github.io/ke2-admin-manual/) を参考にしてみてください。
+
+### 6.2. Kompira 運用自動化コラム
 
 Kompira の実践的な使い方やジョブフローの書き方については [運用自動化コラム](https://www.kompira.jp/column/) を参考にしてみてください。
 
-### 6.2. Kompira コミュニティサイト
+### 6.3. Kompira コミュニティサイト
 
-Kompira の使い方が分からない場合などは、 [コミュニティ> KompiraEnterprise関連](https://kompira.zendesk.com/hc/ja/community/topics/360000014321-KompiraEnterprise%E9%96%A2%E9%80%A3) を参考にしてみてください。同じような質問や回答が見つからない場合は、新たに投稿してみてください。
+Kompira の使い方が分からない場合などは、 [コミュニティ> KompiraEnterprise関連](https://kompira.zendesk.com/hc/ja/community/topics/360000014321-KompiraEnterprise%E9%96%A2%E9%80%A3) を参考にしてみてください。同じような質問や回答が見つからない場合は、新たに投稿してみてください。

ke2/services/fluentd.yml

@@ -1,7 +1,7 @@
 services:
   fluentd:
     image: kompira.azurecr.io/fluentd-with-rewrite-plugin:latest
-    hostname: fl-${HOSTNAME}
+    hostname: fl-${HOSTNAME:?HOSTNAME must be set}
     environment:
       TZ: ${TZ:-Asia/Tokyo}
     configs:

ke2/services/jobmngrd.yml

@@ -1,13 +1,18 @@
 services:
   jobmngrd:
     image: ${KOMPIRA_IMAGE_NAME:-kompira.azurecr.io/kompira-enterprise}:${KOMPIRA_IMAGE_TAG:-latest}
-    hostname: jm-${HOSTNAME}
+    hostname: jm-${HOSTNAME:?HOSTNAME must be set}
     init: true
     environment:
-      - AMQP_URL=${AMQP_URL:-amqp://guest:guest@rabbitmq:5672}
-      - TZ=${TZ:-Asia/Tokyo}
-      - LOGGING_LEVEL=${JOBMNGRD_LOGGING_LEVEL:-${LOGGING_LEVEL:-INFO}}
-      - LOGGING_NAME=jobmngrd
+      AMQP_URL: ${AMQP_URL:-amqp://guest:guest@rabbitmq:5672}
+      TZ: ${TZ:-Asia/Tokyo}
+      LOGGING_NAME: jobmngrd
+      LOGGING_STREAM: ${JOBMNGRD_LOGGING_STREAM:-${LOGGING_STREAM:-true}}
+      LOGGING_LEVEL: ${JOBMNGRD_LOGGING_LEVEL:-${LOGGING_LEVEL:-INFO}}
+      LOGGING_DIR: ${JOBMNGRD_LOGGING_DIR:-${LOGGING_DIR:-/var/log/kompira}}
+      LOGGING_BACKUP: ${JOBMNGRD_LOGGING_BACKUP:-${LOGGING_BACKUP:-7}}
+      LOGGING_WHEN: ${JOBMNGRD_LOGGING_WHEN:-${LOGGING_WHEN:-MIDNIGHT}}
+      LOGGING_INTERVAL: ${JOBMNGRD_LOGGING_INTERVAL:-${LOGGING_INTERVAL:-1}}
     configs:
       - source: kompira-config
         target: /opt/kompira/kompira.conf

ke2/services/kompira.yml

@@ -17,16 +17,26 @@ x-kompira-common-environ:
   CACHE_URL: ${CACHE_URL:-redis://redis:6379}
   LANGUAGE_CODE: ${LANGUAGE_CODE:-ja}
   TZ: ${TZ:-Asia/Tokyo}
-  KOMPIRA_AUDIT_LOGGING_LEVEL: ${AUDIT_LOGGING_LEVEL:-}
 
 services:
   kengine:
     <<: *kompira-common-settings
     environment:
       <<: *kompira-common-environ
-      LOGGING_LEVEL: ${KENGINE_LOGGING_LEVEL:-${LOGGING_LEVEL:-INFO}}
+      MAX_EXECUTOR_NUM: ${MAX_EXECUTOR_NUM:-0}
       LOGGING_NAME: kengine
-    hostname: ke-${HOSTNAME}
+      LOGGING_STREAM: ${KENGINE_LOGGING_STREAM:-${LOGGING_STREAM:-true}}
+      LOGGING_LEVEL: ${KENGINE_LOGGING_LEVEL:-${LOGGING_LEVEL:-INFO}}
+      LOGGING_DIR: ${KENGINE_LOGGING_DIR:-${LOGGING_DIR:-/var/log/kompira}}
+      LOGGING_BACKUP: ${KENGINE_LOGGING_BACKUP:-${LOGGING_BACKUP:-7}}
+      LOGGING_WHEN: ${KENGINE_LOGGING_WHEN:-${LOGGING_WHEN:-MIDNIGHT}}
+      LOGGING_INTERVAL: ${KENGINE_LOGGING_INTERVAL:-${LOGGING_INTERVAL:-1}}
+      AUDIT_LOGGING_LEVEL: ${KENGINE_AUDIT_LOGGING_LEVEL:-${AUDIT_LOGGING_LEVEL:-2}}
+      AUDIT_LOGGING_DIR: ${KENGINE_AUDIT_LOGGING_DIR:-${AUDIT_LOGGING_DIR:-/var/log/kompira}}
+      AUDIT_LOGGING_BACKUP: ${KENGINE_AUDIT_LOGGING_BACKUP:-${AUDIT_LOGGING_BACKUP:-365}}
+      AUDIT_LOGGING_WHEN: ${KENGINE_AUDIT_LOGGING_WHEN:-${AUDIT_LOGGING_WHEN:-MIDNIGHT}}
+      AUDIT_LOGGING_INTERVAL: ${KENGINE_AUDIT_LOGGING_INTERVAL:-${AUDIT_LOGGING_INTERVAL:-1}}
+    hostname: ke-${HOSTNAME:?HOSTNAME must be set}
     init: true
     command: ["kompirad"]
     ulimits:
@@ -36,9 +46,19 @@ services:
     <<: *kompira-common-settings
     environment:
       <<: *kompira-common-environ
-      LOGGING_LEVEL: ${KOMPIRA_LOGGING_LEVEL:-${LOGGING_LEVEL:-INFO}}
       LOGGING_NAME: kompira
-    hostname: ap-${HOSTNAME}
+      LOGGING_STREAM: ${KOMPIRA_LOGGING_STREAM:-${LOGGING_STREAM:-true}}
+      LOGGING_LEVEL: ${KOMPIRA_LOGGING_LEVEL:-${LOGGING_LEVEL:-INFO}}
+      LOGGING_DIR: ${KOMPIRA_LOGGING_DIR:-${LOGGING_DIR:-/var/log/kompira}}
+      LOGGING_BACKUP: ${KOMPIRA_LOGGING_BACKUP:-${LOGGING_BACKUP:-7}}
+      LOGGING_WHEN: ${KOMPIRA_LOGGING_WHEN:-${LOGGING_WHEN:-MIDNIGHT}}
+      LOGGING_INTERVAL: ${KOMPIRA_LOGGING_INTERVAL:-${LOGGING_INTERVAL:-1}}
+      AUDIT_LOGGING_LEVEL: ${KOMPIRA_AUDIT_LOGGING_LEVEL:-${AUDIT_LOGGING_LEVEL:-2}}
+      AUDIT_LOGGING_DIR: ${KOMPIRA_AUDIT_LOGGING_DIR:-${AUDIT_LOGGING_DIR:-/var/log/kompira}}
+      AUDIT_LOGGING_BACKUP: ${KOMPIRA_AUDIT_LOGGING_BACKUP:-${AUDIT_LOGGING_BACKUP:-365}}
+      AUDIT_LOGGING_WHEN: ${KOMPIRA_AUDIT_LOGGING_WHEN:-${AUDIT_LOGGING_WHEN:-MIDNIGHT}}
+      AUDIT_LOGGING_INTERVAL: ${KOMPIRA_AUDIT_LOGGING_INTERVAL:-${AUDIT_LOGGING_INTERVAL:-1}}
+    hostname: ap-${HOSTNAME:?HOSTNAME must be set}
     init: true
     command: ["uwsgi"]
     stop_signal: SIGINT

ke2/services/nginx.yml

@@ -1,7 +1,7 @@
 services:
   nginx:
     image: registry.hub.docker.com/library/nginx:1.27-alpine
-    hostname: nx-${HOSTNAME}
+    hostname: nx-${HOSTNAME:?HOSTNAME must be set}
     environment:
       - TZ=${TZ:-Asia/Tokyo}
       - NGINX_ENVSUBST_FILTER=^KOMPIRA

ke2/services/postgres.yml

@@ -2,7 +2,7 @@ services:
   postgres:
     # MEMO: potgrsql のメジャーバージョンを変更するときは PGDATA 領域のボリューム名も変更すること
     image: registry.hub.docker.com/library/postgres:16.3-alpine
-    hostname: db-${HOSTNAME}
+    hostname: db-${HOSTNAME:?HOSTNAME must be set}
     environment:
       POSTGRES_PASSWORD: kompira
       POSTGRES_USER: kompira

ke2/services/rabbitmq.yml

@@ -1,7 +1,7 @@
 services:
   rabbitmq:
     image: registry.hub.docker.com/library/rabbitmq:3.13-alpine
-    hostname: mq-${HOSTNAME}
+    hostname: mq-${HOSTNAME:?HOSTNAME must be set}
     environment:
       RABBITMQ_DATA_DIR: /var/lib/rabbitmq
       TZ: ${TZ:-Asia/Tokyo}

ke2/services/redis.yml

@@ -1,6 +1,6 @@
 services:
   redis:
     image: registry.hub.docker.com/library/redis:7.2-alpine
-    hostname: re-${HOSTNAME}
+    hostname: re-${HOSTNAME:?HOSTNAME must be set}
     environment:
       - TZ=${TZ:-Asia/Tokyo}