KE2.0 移行ガイド # 1. はじめに Kompira enterprise v2.0 系は v1.6 系からアーキテクチャが大きく変わり、ジョブフローの仕様にも変更がありました。Kompira enterprise v1.6 系で動作している自動化システムを v2.0 系に移行したいとき、着実にシステムを移行させるためには事前に移行計画や移行手順を検討する必要があります。 このガイド資料は、KE2.0 への移行計画や移行手順を検討するうえで手助けとなるよう作成していますので、参考にしてみてください。 ## 1.1. 変更履歴 | 日付 | 担当 | 備考 | | --- | --- | --- | | 2024/11/26 | FP鈴木 | 初版作成 | | 2024/12/27 | FP髙橋 | 「3. 移行計画の検討」の追加／全体的に加筆 | # 2. 前提条件 本ガイドにおける前提条件を以下に示します。 ## 2.1. 移行方式について - **本ガイドでは移行時にシステムの一時停止を伴う方式を前提とします。** - 無停止での移行については一般的に難易度が高く、システム固有に検討すべき事項が増えるため、本ガイドの対象外とします。 ## 2.2. 移行元システムについて - **移行元の環境は Kompira Enterprise v1.6 系の v1.6.4 以降とします。** - v1.6.3 以前をご利用中の場合は、事前に v1.6.4 以降にアップデートしてから v2.0 系への移行を検討するようにしてください。 - v1.6 系のアップデートの注意点については以下の資料を参考にしてください。 - https://docbase.io/posts/2678628/sharing/c9fd6a81-53ed-4cd7-87b5-45042e71635c ## 2.3. 移行先システムについて - **移行先は Kompira Enterprise v2.0 系の v2.0.0 以降とします。** - v2.0 系においては v2.0.2 でライセンス管理における system_id の算出方法が変更になっていますので、新たに移行する場合は **v2.0.2 以降に移行することをお勧めします**。 ## 2.4. 構築手順および管理手順について - **KE 2.0 システム自体の構築手順や管理手順については本ガイドの対象外です。** - KE 2.0 システムの構築手順や管理手順については、以下の KE2.0 管理者マニュアルを適宜参照してください。 - https://fixpoint.github.io/ke2-admin-manual/ - KE 2.0 システムを構築するときに必要となる Docker 定義ファイルなどについては、以下リポジトリから取得できます。 - https://github.com/fixpoint/ke2-docker/ ## 2.5. その他 - **移行先の環境にはライセンスが適用されていることを前提とします。** - v1.6 系でお使いのライセンスを v2.0 系に適用することはできません。 - 移行先の環境に構成に応じた v2.0 用ライセンスを適用してから作業を実施してください。 - v1.6 系ライセンスから v2.0 系ライセンスへの切り替えについては、フィックスポイントライセンス窓口までご依頼ください。 - **v2.0 系でメール送信を行う場合は、Kompira Enterprise サーバとは別に SMTP サーバが必要です 。** - v1.6 系で外部 SMTP サーバを使用せずにメール送信を行なっていた場合は、お客様ご自身で新規 SMTP サーバをご用意いただく必要があることにご注意ください。 # 3. 移行計画の検討 システム移行の計画を立てるためには様々な項目を検討する必要があります。以下では一般的に必要になると考えられる検討項目を示しますので、参考にしてみてください。 - 移行スケジュールの計画 - 移行元システムの状況確認 - 移行方針の検討 - 移行先システムの構成検討 - 移行先システムの準備 - システム移行作業の検討 - プログラムの移行作業 - データの移行作業 - 移行先システムでの動作確認 - システムの切り替え - 移行元システムの削除 ## 3.1. 移行スケジュールの計画 システム移行に際して必要な作業を検討してスケジュールを計画してください。 - 次節以降に示す各項目について検討に要する期間、実際移行作業を行なう期間、その後の動作確認などを実施する期間、などを加味してスケジュールを検討するようにしてください。 - システム移行に関して経験やノウハウが不足している場合は、余裕を持った移行期間を確保することをお勧めします。 - 後述しますが、移行するシステムにパフォーマンス要件がある場合は、移行方針によってスケジュールの立て方が変わると思いますので、注意深く計画するようにしてください。 ## 3.2. 移行元システムの確認 移行計画を検討するうえで移行元システムについて十分理解しておくことが重要になります。以下では KE2.0 への移行を計画するうえで特に重要な確認ポイントをいくつか示します。 - 移行元システムの不具合有無の確認 - 移行元システムに現状なんらかの不具合があるかどうか確認しておいてください。 - 移行前から不具合があるような場合は、移行作業に成功しても移行後も同じ不具合を抱えるか、移行作業に何らかの問題があった場合はより複雑な状況に陥る可能性があります。できれば移行作業前に不具合を修正しておくことをお勧めします。 - 移行作業で不具合の修正を合わせて行なうことも出来るとは思いますが、上記のようなリスクに注意して計画するようにしてください。 - 移行元システムの設計資料の確認 - 設計資料があれば、KE2.0 移行に際してシステムの設計や実装に修正を加える必要があるかの判断や、どのような修正を行なうべきかの検討材料になります。 - 設計資料が無い場合は、設計資料の作成を移行計画に含めることをお勧めします。 - 移行元システムの動作確認項目の確認 - 動作確認項目の資料があれば、システム移行後に動作確認を行なうべき項目の検討材料になります。たとえば以下のように、どのような動作確認を実施するかを検討してください。 - システム移行後に確認項目をすべて再度確認する、あるいは、重要度の高い項目だけ動作確認を実施する。基本的には前者をお勧めしますが、後者より時間はかかることになります。 - 移行にともなって仕様や動作を見直す場合は、関連する確認項目も合わせて見直して実施するようにする。 - 動作確認項目の資料が無い場合は、確認項目の作成を移行計画に含めることをお勧めします。 - 移行元システムの規模の確認 - 移行元システムのジョブフローやスクリプトジョブ、ライブラリなどプログラム類の数や、突出して大きい（行数の多い）ものがないか、などを確認しておいてください。 - 移行元システムのデータ系オブジェクトや設定オブジェクトなどの種類や総数を確認しておいてください。 - それぞれ数が多いほど、複雑さがあるほど、移行方針の検討や実際の移行作業にも時間がかかることを考慮するようにしてください。 - 追加 Python モジュールの確認 - 移行元システムで追加の Python モジュールをインストールして、ライブラリオブジェクトから利用している処理の有無と、有る場合はその処理内容について確認しておいてください。 - KE2.0 系では Kompira が利用している Python バージョンが異なっています（v2.0.0 時点では Python 3.11 系を採用しています）。追加の Python モジュールが、KE 2.0 系の Python バージョンでも利用できるか確認するようにしてください。 - KE2.0 系では Python パッケージの管理手順も変わっています。KE2.0 管理者マニュアルでは PIP パッケージのインストール方法を示していますので、参考にしてみてください。 - https://fixpoint.github.io/ke2-admin-manual/management/package/packages_info.html - ローカルコマンド処理の確認 - 移行元システムで Kompira サーバでコマンド実行する処理の有無と、有る場合はその処理内容について確認しておいてください。 - KE2.0 系ではローカルコマンドは jobmngrd コンテナ内部で実行されます。jobmngrd コンテナは（v2.0.0 時点では）[python:3.11-alpine コンテナ](https://hub.docker.com/_/python)をベースにいくつかコマンドを追加したものになっており、KE1.6 のサポート OS とは含まれているコマンドに差異があります。 - 利用しているコマンドが jobmngrd コンテナに含まれていない場合は、システム構築時にコマンドを追加インストールするかリモートコマンドに置き換える、あるいはコマンド以外の処理方式に変更する（例えば Python ライブラリ化する）、などといった検討が必要になります。 - ファイル操作処理の確認 - 移行元システムでファイル操作を行なう処理の有無と、有る場合はその処理内容について確認しておいてください。 - KE2.0 系ではコマンド実行ジョブやファイル転送を行なう get() / put() ジョブは jobmngrd コンテナ内部で実行される一方、ライブラリの呼び出しは kengine コンテナ内部で行われます。そのため、例えばコマンドの実行結果をファイルに出力させて、ライブラリでそのファイルを読み込んで後続の処理を行なう、といったファイル操作を行なっている場合は注意が必要になります。 - 通常コンテナ内部でのファイル操作は別のコンテナに影響を与えないため、jobmngrd コンテナ内部に書き出したファイルを kengine コンテナから読み込むことは出来ません。これに対してはシステム構成として対処する必要があります。たとえばホストを介して各 docker コンテナでディレクトリを共有できるようにマウントの設定を追加しておき、コマンドによりファイル操作もライブラリによるファイル操作も同じ共有ディレクトリ上で処理する、といった方式があります。 - クラスタ構成の場合はさらに注意が必要になります。クラスタ構成では、複数の jobmngrd コンテナおよび複数の kengine コンテナが、複数のホスト上で動作しますので、ディレクトリの共有はホストを介するだけでは不十分です。各ホスト間においてもディレクトリの共有が必要になりますので、たとえばネットワークファイルシステムを準備して各ホストで共有ディレクトリをマウントするようにして、さらにホスト上の jobmngrd, kengine コンテナでマウントするように設定する、といったシステム構成が必要になります。 - KE2.0 管理者マニュアルでは、Swarm クラスタ構成において GlusterFS を用いてコンテナ間で共有ディレクトリにアクセスできるようにするシステム構成例を示していますので、参考にしてみてください。 - https://fixpoint.github.io/ke2-admin-manual/setup/cluster/swarm/index.html - 外部ジョブマネージャおよび kompira_sendevt 利用の確認 - 移行元システムにおいて、外部ジョブマネージャを配置してリモートジョブの連携を行なっているか、また、外部サーバに kompira_sendevt をインストールして Kompira サーバにイベント送信の連携を行なっているかを確認してください。 - 外部から AMQPS 接続するためには KE2.0 システム側に準備が必要になります。以下を参考にしてみてください。 - https://fixpoint.github.io/ke2-admin-manual/setup/external/index.html - 外部にジョブマネージャに構築する手順については、以下を参考にしてみてください。 - https://fixpoint.github.io/ke2-admin-manual/setup/external/jobmngrd/index.html - 外部サーバに kompira_sendevt をインストールする手順については、以下を参考にしてみてください。 - https://fixpoint.github.io/ke2-admin-manual/setup/external/sendevt/index.html ## 3.3. 移行方針の検討 全体的な移行方針を検討して計画に反映するようにしてください。 - 移行先の環境を検討してください。 - 本番環境のみ移行するのか、検証環境や開発環境なども移行する／新たに用意するのか、などを検討してください。 - 用意する環境の数やバリエーションによって、作業の量も変わると思いますので計画に反映するようにしてください。 - プログラムの移行について検討してください。 - 移行元システムのプログラム（ジョブフロー、スクリプトジョブ、Pythonライブラリなど）をそのまま移植するのか、移行のタイミングで機能追加・変更・修正を行なうのか、などを検討してください。 - 機能の追加・変更・修正を行なう場合は、それらについての設計や動作確認の方針についても検討するようにしてください。 - そのまま移植だけする場合でも、KE 2.0 の仕様変更に合わせて修正が必要になる場合があります。「4.2. ジョブフローの修正作業」などを参考にして、移行で必要になる作業について検討してください。 - データや設定の移行について検討してください。 - プログラム以外にデータや設定がある場合は、それらを単純にコピーするように移行すればよいのか、移行に際してデータ変換作業や設定の変更が必要になるのかなどを検討してください。 - データ変換や設定変更が必要な場合でも、その複雑さや対象のオブジェクト数などをもとに、どのように実施するかを検討してください。例えば以下のような方式が考えられます。 - 移行先システムにデータ一式をインポートしたあとに、必要な箇所を手作業で変更する。あるいは変換処理を実施するジョブフローを作成して、一括適用する。 - 移行元システムからエクスポートしたデータに対してスクリプトなどで変換処理を施してから、移行先システムにインポートする。 - 移行作業中にも移行元システムでデータが増減して、そのデータが移行先システムの動作に必要になるような場合は、とくに注意するようにしてください。どのようにシステムを切り替えるのか、また、どのようにデータを移行するのかを、合わせて検討してください。 - パフォーマンス要件について検討してください。 - KE1.6系とKE2.0系ではパフォーマンス特性が異なるため、システムにパフォーマンス要件がある場合は、移行に際しては注意が必要になります。 - KE2.0系ではシステムアーキテクチャの変更により、単一ノード（単一エグゼキュータ）あたりの処理パフォーマンスについてはKE1.6系より低下する場合があります。一方で KE2.0 ではマルチエグゼキュータ構成による並列動作に対応しており、システム構成（マルチノード構成やマルチエグゼキュータ構成）とシステム設計（ジョブフロー設計の見直し）によっては、全体の処理パフォーマンスの向上を狙うこともできます。 - システムにパフォーマンス要件がある場合は、こうした特性の違いを踏まえて移行方針を検討してください。たとえば、以下のような方針の考え方があるかと思います。 - パフォーマンス要件が無い場合／重要度が低い場合：システム移行を優先して実施して、その後の動作確認やパフォーマンス測定などを経て、必要に応じてシステムの改善を改めて検討する。 - パフォーマンス要件が重要である場合：システム全体の移行を実施する前に、パフォーマンスを重視する処理のみを KE2.0 系に移植してパフォーマンス評価を実施する。例えばベンチマークを実施して、要件を満たすかどうかを確認する。未達の場合はシステム構成やシステム設計の見直しと再評価を繰り返し、目標を達成しうるか検討する。 ## 3.4. 移行先システムの構成検討 移行先システムをどのような構成にするかを検討してください。ただし、全ての組み合わせが実現可能であるとは限りません。弊社でサポートしているシステム構成については、KE2.0 管理者マニュアルの「[構築ガイド](https://fixpoint.github.io/ke2-admin-manual/setup/index.html)」を参考にしてみてください。 - システム構成 - プラットフォーム - 物理サーバ、仮想サーバ - クラウド上のコンテナサービスなど - ノード構成 - シングル構成 - １ノードに全てのコンテナを動作させる構成になります。 - シンプルな構成なため構築や管理といった面で、クラスタ構成よりも簡単になります。 - クラスタ構成 - 複数のノード（3台以上）にコンテナを配置して動作させる構成になります。 - 各ノードにエンジンを配置することで、ジョブフロー動作の並列度を上げることが可能になります。 - データベース構成 - 内部データベース構成 - Kompira システム内部にデータベースコンテナを動作させる構成になります。 - 外部データベース構成 - Kompira システム外部に配置されたデータベースに接続する構成になります。 - エグゼキュータ数 - 合計エグゼキュータ数 - エグゼキュータの数だけジョブフローを並列に動作させることができます。 - デフォルトでは合計エグゼキュータ数は 2 となります。 - エンジンあたりのエグゼキュータ数 - デフォルトではノードに搭載された CPU コア数になります。 - ノード構成と合計エグゼキュータ数から適切な設定値を算出します。 - 本番環境以外がある場合は、それらを同じ構成にするのか、異なる構成にするのか検討してください。 - 各環境の構成を揃えておくことで、構成に依存した問題を生じにくくすると考えることは出来ます。一方で、構成違いの環境があれば、構成に依存した問題点を事前に検出しやすいとも言えます。 - 環境によって構成を調整することで、システム全体の維持コストを削減できる可能性があります。 - 構成によって必要になるライセンスが異なることにも注意してください。 - 合計エグゼキュータ数を 2 より大きくしたい場合は、追加エグゼキュータオプションをご契約いただく必要があります。 - マルチノード構成にする場合は3台以上での構成となるため、必要な合計エグゼキュータ数も必然的に3以上となり、追加エグゼキュータオプションが必要となります。 ## 3.5. 移行先システムの準備 移行先システムの準備としては以下のような作業が必要になります。 - 移行先プラットフォームの準備 - 検討したシステム構成に合わせてプラットフォーム環境、たとえば物理サーバや仮想サーバなどを準備してください。 - KE2.0 システムのデプロイ - KE2.0 管理者マニュアルの「[構築ガイド](https://fixpoint.github.io/ke2-admin-manual/setup/index.html)」を参考にして、構成に合わせた手順でシステムをデプロイしてください。 この時点で移行先システムの準備作業に着手できるかと思います。また、この準備作業と次の「システム移行作業の検討」は並列して実施できますので、作業を分担することも検討してみてください。 ## 3.6. システム移行作業の検討 実際のシステム移行として必要になる以下のような作業の内容を検討してください。具体的には本ガイドの「4. システム移行作業の検討」を参考にしてください。 - プログラムやデータの移行作業 - ジョブフローの修正作業 - システム構成変更に伴う移行作業 ## 3.7. データの移行作業 データの移行作業を検討してください。データの変換作業や設定変更などについては、プログラムの移行作業と並行して実施する、もしくはプログラムの移行後に実施したほうがよい場合もあると思いますので、作業順は内容に応じて調整するようにしてみてください。 - データや設定の移行作業を実施してください。 - 移行に伴ってデータ変換作業が必要な場合 - Kompira 上での手作業によるデータ変換 - Kompira 外でのデータ変換処理とデータインポート - 移行に伴って設定変更が必要になる項目 ## 3.8. プログラムの移行作業 プログラムの移行作業を検討してください。ジョブフローやスクリプトが単体で正常に動作するかはこの段階で確認しておくことをお勧めします。 - 「3.X プログラム移行手順の検討」で検討した移行手順に従って、ジョブフローやスクリプトジョブ、ライブラリオブジェクトなどの修正を行なってください。 - KE2.0 における仕様変更に伴って修正した部分については、とくに重点的に修正箇所ごとに動作確認を行なうようにしてください。 ## 3.9. 移行先システムでの動作確認 システム移行で最も重要となるシステム全体が正常に動作するかの確認作業となります。 - プログラムとデータの移行作業が完了したら、「3.X. 移行方針の検討」で検討した動作確認の方針に従って、移行先システムでの動作確認を実施してください。 - 不具合が見つかった場合は、プログラムやデータなどに誤りがないか確認して再度検証する、という作業を繰り返してください。 - プログラムやデータに誤りが見いだせない場合は、KE2.0 における仕様変更の理解を誤っていたり、修正方針自体が誤っていたりする可能性、また、KE 2.0 自体に不具合が残っている可能性などが考えられます。 - 動作確認と修正を繰り返しても、原因が特定できないような場合は、サポート担当窓口またはコミュニティサイトにて問い合わせてみてください。 ## 3.10. システムの切り替え - システムの動作確認が完了したら、移行元システムから移行先システムへの切り替えを実施してください。 - ただし、実際に切り替える手順についてはシステム個別に依存するので、具体的には示すことができません。以下を参考にしてみてください。 - Kompira が受動的に動作する場合: - 外部システムから Kompira に働きかけるような連携を行なっている場合は、外部システム側で連携先の Kompira を移行元から移行先に切り替える、といった作業を検討してください。 - Kompira が能動的に動作する場合: - 移行元システムを安全に停止してから、移行先システムを開始するようにしてください。 ## 3.11. 移行元システムの削除 - システムの切り替えが完了したら、移行元のシステムは削除することができます。 # 4. システム移行作業の検討 ジョブフローやその他 Kompira オブジェクトは基本的にはそのまま移行可能ですが、実行環境の変更に伴い何点かの修正を検討する必要があります。 - プログラムやデータの移行作業 - 移行元で Kompira オブジェクトのエクスポート - 移行先の v2.0 環境で移行元からエクスポートしたデータをインポート - ジョブフローの修正作業 - v2.0 で廃止・仕様変更となった機能を使っている場合は、代替の実装への修正 - Kompira の実行環境が Docker コンテナに変更されたことに伴う修正 - マルチ Executor / Engine 化に伴う修正 - システム構成変更に伴う移行作業 - ログ出力設定の検討 - 外部連携の検討 - クラスタ構成（冗長構成）の場合の検討 ## 4.1. プログラムやデータの移行作業 - 移行元で Kompira オブジェクトのエクスポート - 移行先の v2.0 環境で移行元からエクスポートしたデータをインポート ### 4.1.1. 移行元で Kompira オブジェクトのエクスポート 移行元で下記のコマンドを実行し、移行元の Kompira オブジェクトをエクスポートします。 ``` # /opt/kompira/bin/manage.py export_data / --virtual-mode > export_data.json ``` 【補足】この例では仮想オブジェクトを含む全てのオブジェクトを一度にエクスポートしています。オブジェクト数が非常に多い場合など、エクスポートデータのサイズが大きくなりすぎることもあるかと思います。そうした場合は、エクスポートするディレクトリの起点を調整したり（プログラム類とデータ類を別々にエクスポートするなど）、仮想オブジェクトは対象外にしたりするなど、エクスポートする範囲を調整するようにしてみてください。 エクスポートしたファイルは、何らかの手段で移行先のホストサーバに転送してください。 ### 4.1.2. 移行先で移行元からエクスポートしたデータをインポート 移行先で下記のコマンドを実行し、移行元でエクスポートしたデータをインポートします。 まず、docker cp コマンドでエクスポートデータ（export_data.json ファイル）を kompira コンテナ内部にコピーしてください。エクスポートデータを複数に分割している場合はすべてコピーしてください。 ``` # docker cp ./export_data.json $(docker ps -q -f name=kompira):/tmp/ ``` 次に、kompira コンテナ内部で manage.py import_data コマンドを用いて、エクスポートデータを Kompira データベースにインポートしてください。 ``` # docker exec $(docker ps -q -f name=kompira) manage.py import_data /tmp/export_data.json --overwrite-mode ``` ## 4.2. ジョブフローの修正作業 - v2.0 で廃止・仕様変更となった機能を使っている場合の修正 - チャネルの message_queue、event_queue に対する内部アクセスの禁止 - メールチャネルのポーリング仕様の変更 - mailto() への複数メールアドレスを指定方法の修正 - Kompira の実行環境が Docker コンテナに変更されたことに伴う修正 - ホストを指定しないコマンド実行ジョブ - ファイルアップロード、ダウンロード - マルチ Executor / Engine 化に伴う修正 - 排他制御 - spawn() の利用 ### 4.2.1. v2.0 で廃止・仕様変更となった機能を代替実装に修正 KE 2.0 系ではジョブフローの仕様においても廃止や変更があります。移行前のシステムで該当する箇所がある場合はジョブフローの設計や実装を修正する必要があります。 #### 4.2.1.2. チャネルの message_queue、event_queue に対する内部アクセスの禁止 KE 1.6 系まではチャネル（チャネルオブジェクト、オンメモリチャネル、セッションチャネル）の message_queue や event_queue の中身を参照したり、値を変更したりすることが出来ましたが、KE 2.0 系ではこれらの操作が禁止となりました。 移行前システムのジョブフローでこのような操作を行なっている場合、そのままでは KE2.0 系では実行時エラーとなりますので、代替実装への修正や処理自体の見直しを行なってください。 ##### 【要修正】message_queue の中身を参照している 例えば以下のようなジョブフローは KE 2.0 系では実行時エラーになります。 ``` print(chan.message_queue[1]) ``` message_queue の中身を直接参照しないようにしてください。代わりに `Channel.peek_message()` メソッドを使うことを検討してみてください。 ``` [peek_result = chan.peek_message(1)] -> [message_id = peek_result[0], message_body = peek_result[1]] -> print(message_body) ``` ##### 【要修正】message_queue の中身を変更している 例えば以下のようなジョブフローは KE 2.0 系では実行時エラーになります。 ``` [["foo", "bar", "baz"] >> chan.message_queue] ``` または ``` [chan.message_queue.add_item: "foo"] ``` message_queue の中身を直接変更しないようにしてください。代わりに `Channel.send()` メソッド を使うことを検討してみてください。 ``` [chan.send: "foo"] -> [chan.send: "bar"] -> [chan.send: "baz"] ``` ##### 【要修正】event_queue の中身を参照している 例えば以下のようなジョブフローは KE 2.0 系では実行時エラーになります。 ``` print(chan.event_queue[1]) ``` event_queue の中身を参照しないようにしてください。KE2.0 系では event_queue の中身の参照自体が禁止事項となりましたので、代替手段はありません。 #### 4.2.1.3. メールチャネルのポーリング仕様の変更 KE 1.6 系までのメールチャネルは、実行中のジョブフローによる受信待ちが無い（受信待ちイベントが無い）ときはメールサーバに対して受信を行なうポーリング処理が停止するようになっていました（メールチャネルにアクションジョブフローが設定されていない場合）。 ``` # 1.6 系では受信待ちによってポーリングが開始していた ``` KE 2.0 系ではこのポーリング動作の仕様が変更されて、**メールチャネルが有効化されている場合は、ジョブフローによる受信待ちの有無に関係なく常にポーリングが行なわれるようになりました**。 この変更により、以前であればポーリングが行なわれないようなタイミングでメールサーバからメールの受信処理が行なわれることになりますので注意してください。例えば、有効化フラグがセットされたメールチャネルを含むデータをインポートすると、その直後からメールサーバへのポーリングが開始されることになります。 データをインポートまたはエクスポートするときなど、メールチャネルの受信ポーリングが停止しているほうが都合がよい、という場面もあると思います。そうしたときは、メールチャネルの有効化フラグをクリアしておくことで対処するようにしてみてください。ただし、ジョブフローを開始する前に再度有効化することを忘れないように注意してください。 またこの変更は、例えば「ジョブフローを実行（してメールチャネルの受信待ちを開始）するまでメールサーバへの受信ポーリングは始まらない」あるいは「ジョブフローを開始するとメールサーバからメールが受信される」といった振る舞いになることを、システムの正常な動作の判定に用いていると、KE 2.0 系では判断を誤る可能性があります。システムの動作確認項目にそのような項目がある場合は、判定条件を見直すようにしてください。 #### 4.2.1.4. mailto() で複数メールアドレスを指定方法の修正 メール送信を行なう `mailto()` ジョブはパラメータ `to` や `cc` で送信先メールアドレスを指定します。送信先として複数のメールアドレスを指定するにはパラメータに配列で渡す方法がありますが、以下のように文字列中に複数のメールアドレスを列挙して渡すことも出来ます。 ``` mailto(to="foo@example.co.jp, bar@example.co.jp", ...) ``` このようにカンマ `,` を区切り文字としてメールアドレスを列挙している場合は問題ありませんが、**セミコロン `;` などを区切り文字に使っていると、実行時エラーになります**（厳密には利用している Python のバージョンによってエラーになる場合とならない場合があります）。 ``` mailto(to="foo@example.co.jp; bar@example.co.jp", ...) # NG ``` 移行前のシステムでメールの宛先の区切り文字にカンマ以外を利用していないか確認してください。該当する場合は、複数のメールアドレスは配列で渡すようにするか、区切り文字にカンマ `,` を利用するように修正してください。 【補足】メールアドレスを列挙するときはカンマ `,` を区切り文字として利用するべきなのですが、メールの処理系によってはセミコロン `;` なども区切りとして使えていた過去の経緯があります。Python においても例えばセミコロン `;` を区切り文字として利用できていたのですが、脆弱性 CVE-2023-27043 の修正として形式チェックが強化されてエラーになるようになりました。そのため、脆弱性のパッチが適用されている Python バージョンではエラーになり、未適用の Python バージョンではエラーにならない、という振る舞いの違いが生じます。 ### 4.2.2. Kompira の実行環境が Docker コンテナに変更されたことに伴う修正 KE 1.6 系までは各コンポーネントはサーバ上のサービス（プロセス）として動作していましたが、KE 2.0 系では各コンポーネントが Docker コンテナとして動作するようにアーキテクチャが変更されました。 これに伴い、現行システムを KE 2.0 系に移行する際に、ジョブフローの設計や実装やシステムの構成や設定などについて修正する必要がある場合があります。 #### 4.2.2.1: ホストを指定しないコマンド実行ジョブ 以下のようなホストを指定しないコマンド実行ジョブは、KE1.6 系では Kompira をインストールしたサーバ（OS）上で実行されます。 ``` ['hostname'] ``` 一方 KE2.0 系で同じジョブフローを実行すると、コマンドは jobmngrd コンテナ内部で実行されます。ジョブフローでこのようにローカルでのコマンド実行を利用しているシステムを KE2.0 系に移行する場合は、注意が必要になります。 【補足】クラスタ構成の場合、リモートジョブはいずれかのノード上の jobmngrd コンテナで実行されます。ジョブフロープロセスを実行している kengine コンテナが動作しているノードと同じノード上の jobmngrd コンテナで実行されるとは限らないことに注意してください。 実行するコマンドが jobmngrd コンテナに含まれている場合は基本的に問題ありません。コマンド自体およびコマンドラインオプションなどに互換性があれば、特に修正作業は不要なはずです（念のため互換性については確認しておくことをお勧めします）。 一方で、実行したいコマンドが標準的なものでない場合は、ジョブフローを実行する前にホストサーバではなく jobmngrd コンテナ内部にインストールしておく必要があります。 例えば、jobmngrd コンテナ内部に perl コマンドを追加するには、以下のように apk コマンドでインストールすることができます（補足：jobmngrd コンテナは Alpine Linux ベースになります）。 ``` # docker exec -it $(docker ps -q -f name=jobmngrd) apk add perl ``` システム構築後（起動後）に jobmngrd コンテナ内部でコマンドを追加でインストールすることで、ジョブフローからそのコマンドを実行できるようにはなります。**ただし、コンテナを再起動するとインストールされる前の初期状態に戻るため、この方式では運用に注意が必要になります。** 例えば、コンテナ再起動のたびに jobmngrd コンテナ内部でインストール操作を実施するようにする、なども考えられます。しかし、運用時の手順モレや、インターネットと接続できない閉鎖環境ではそもそもインストール作業が出来ない、といった懸念もあるためあまりお勧めできません。 やはり何らか修正を伴う対策が必要になります。以下ではいくつか対策案を示しますので参考にしてみてください。 ##### 対策案１ v1.6 でホストを指定せずにコマンド実行をしていた処理を「Kompira が動作しているサーバでのリモートコマンド実行」に置き換えて、必要なコマンドは Kompira が動作しているホストサーバOSにインストールするという方式も考えられます。 例えば先のジョブフローは以下のように置き換えることで、KE 2.0 を構築したサーバにある `hostname` コマンドが実行されます。 ``` { __host__='host.docker.internal', __user__='user', __password__='password' | ['hostname'] } ``` これにより、コンテナ再起動によって追加コマンドが失われる心配や、都度再インストールするといった作業は必要なくなります。 **ただし、この方式ではサーバに SSH 接続してコマンド実行することになるため、ライセンスのノード数を消費してしまうことに注意してください。** ##### 対策案２ ローカルコマンドで行っている処理を、ジョブフローやライブラリの実装に置き換えることができないか検討してみてください。ライブラリオブジェクトを用いて Python で実装することができれば、コマンドを追加でインストールする必要も無くなりますし、リモートコマンドによるライセンスのノード数消費を考慮しなくて済みます。 ``` import socket def hostname(): return socket.gethostname() ``` ただし、この方式では完全に新たな実装を追加する必要があるため、その実装や動作確認を行なうに足るスキルや開発期間が必要になることには注意してください。 #### 4.2.2.2. ホストと jobmngrd コンテナ間のファイル共有（ファイルアップロード、ダウンロード） 前項と同様に `upload()` / `download()` / `put()` / `get()` もリモートジョブですので、KE 2.0 系ではこれらの処理はいずれかの jobmngrd コンテナで実行されます。すなわち、**これらのファイル転送のジョブで指定するファイルのアップロード元やダウンロード先は jobmngrd コンテナ内のディレクトリとなります**。 例えば下記のジョブフローを実行した場合、同じディレクトリの Package 添付ファイルオブジェクトの attached1 フィールドに添付されたファイルは、jobmngrd コンテナ内の /tmp/ に保存されることになります。 ``` download(from_file=./Package.attached1, to_path='/tmp/') ``` この状態ではダウンロードしたファイルをホスト（Kompiraサーバ）から直接参照できません（他のコンテナからも参照できません）。参照するためには、例えば以下のようにホストサーバ上で `docker cp` コマンドを実行してコンテナからホストにファイルをコピーする必要があります（「ファイル名」の部分は添付されていたファイル名に置き換えてください）。 ``` # docker cp $(docker ps -q -f name=jobmngrd):/tmp/ファイル名 ./ ``` アップロードの際も同様で、Kompira オブジェクト上にアップロードしたいファイルはあらかじめ jobmngrd コンテナ内にコピーした状態で、`upload()` を実行する必要があります。 上記のような手順は煩雑ですし、ホスト上での操作が許可されない場面などもあるかと思います。ファイル操作を簡単にするために、システム構成をカスタマイズするなどの対策を検討してみてください。 ##### 対策案１ アップロード元およびダウンロード先として指定するディレクトリをホストと docker コンテナで共有できるように、ボリュームを定義することを検討してみてください。 例えば、ホスト上に `/opt/kompira-shared` というディレクトリを作成して、それを jobmngrd コンテナの `/kompira-shared` というディレクトリにマウントすることを考えてみます。 まず、ホスト上にディレクトリを作成しておきます。また、あと後でコンテナからのアクセスを簡単に確認できるように hello.txt というファイルをホスト側で作成しておきます。 ``` # mkdir -p /opt/kompira-shared # echo HELLO-KOMPIRA > /opt/kompira-shared/hello.txt ``` 次に、以下のようなマウント設定を docker-compose の設定ファイルに追加することで、ホストとコンテナ間でディレクトリの共有が出来るようになります。ファイル（ディレクトリ）の実体はホスト側が持ち、コンテナ側がそれをマウントすることでアクセスできるようになる、という関係性になります。 ``` volumes: - /opt/kompira-shared:/kompira-shared ``` いくつか設定方法は考えられますが、ここでは jobmngrd コンテナの定義している設定ファイル ke2-docker/ke2/services/jobmngrd.yml に、上のボリューム設定を追加してみます。 ``` services: jobmngrd: ...省略... volumes: - ${KOMPIRA_VAR_DIR:-kompira_var}:/var/opt/kompira - ${KOMPIRA_LOG_DIR:-kompira_log}:/var/log/kompira - /opt/kompira-shared:/kompira-shared # 追加したボリューム設定 ``` この設定をもとにコンテナをデプロイすると、jobmgnrd コンテナからディレクトリ /kompira-shared にアクセスすると、ホスト側とファイルが共有されているはずです。例えば以下のように docker exec を用いて、jobmngrd コンテナ内部から先ほどホスト上で作成しておいた hello.txt ファイルにアクセスできることが確認できます。 ``` # docker exec -it $(docker ps -q -f name=jobmngrd) cat /kompira-shared/hello.txt HELLO-KOMPIRA ``` ここで先ほどのジョブフローのダウンロード先を /kompira-shared に変えて実行してみてください。 ``` download(from_file=./Package.attached1, to_path='/kompira-shared/') ``` 今度は、ダウンロードされた添付ファイルがホスト上の /opt/kompira-shared ディレクトリから参照できる（ホスト側にファイルが作られている）ことが確認できるはずです。 #### 4.2.2.3. ホストと kengine コンテナ間のファイル共有 移行元システムにおいて、**ライブラリオブジェクトからファイル操作を行なうような処理がある場合は、そのファイルの配置場所に注意する必要があります**。 KE 1.6 系までのライブラリオブジェクトの呼び出しは kompirad サービス上で行われていました。これはライブラリオブジェクトの Python 実装からサーバ上のファイルに直接アクセスできることを意味します。 例えば以下のようなライブラリオブジェクトを fileio という名前で作成しておき、ジョブフローから呼び出すことでサーバ上のファイルを読み書きすることができます。 ``` def file_read(path, mode="r", encoding="utf-8"): with open(path, mode=mode, encoding=encoding) as f: return f.read() def file_write(path, data, mode="w", encoding="utf-8"): with open(path, mode=mode, encoding=encoding) as f: f.write(data) ``` 一方で、KE 2.0 系ではライブラリオブジェクトの呼び出しは kengine コンテナ内部で行われます。これはライブラリオブジェクトの Python 実装からアクセスできるのは kengine コンテナ内部に限られ、ホストサーバ上（および他のコンテナ内部）のファイルにはアクセスできないことを意味します。 よって、移行元システムでライブラリオブジェクトからファイル操作を行なっている場合は、そのファイルの配置場所を kengine コンテナ内部からアクセスできる場所に変更する必要があります。 例えば事前に kengine コンテナ内部に docker cp コマンドでファイルを転送しておくことで、ライブラリオブジェクトから読み込めるようにはなります。 ただし、前項と同様に手順として煩雑になりますので、ファイル操作を簡単にするために、システム構成をカスタマイズするなどの対策を検討してみてください。 ##### 対策案１ 「4.2.2.2. ホストと jobmngrd コンテナ間のファイル共有」と同様に、kengine コンテナを定義している設定ファイル ke2-docker/ke2/services/kompira.yml に、ボリューム設定を追加してみます。（なお、この設定方法では kengine コンテナだけでなく kompira コンテナにも適用されることになります） ``` x-kompira-common-settings: ...省略... volumes: - ${KOMPIRA_VAR_DIR:-kompira_var}:/var/opt/kompira - ${KOMPIRA_LOG_DIR:-kompira_log}:/var/log/kompira - /opt/kompira-shared:/kompira-shared # 追加したボリューム設定 ``` この設定をもとにコンテナをデプロイすると、kengine コンテナからディレクトリ /kompira-shared にアクセスすると、ホスト側とファイルが共有されているはずです。 先ほどのライブラリオブジェクト（同じディレクトリに fileio という名前である想定です）を、ジョブフローから以下のように呼び出してみてください。 ``` [data = ./fileio.file_read("/kompira-shared/hello.txt")] -> print(data) ``` ホストサーバ上にあるファイル（hello.txt は事前に作成されている前提です）を読み込めていることが確認できるはずです。 #### 4.2.2.4. jobmngrd コンテナと kengine コンテナ間のファイル共有 これまでの説明のとおり、KE 2.0 系では、コマンド実行やファイル転送などのリモートジョブは jobmngrd コンテナで実行され、ライブラリオブジェクトの Python コードの呼び出しは kengine コンテナで実行されます。 このことから「コマンド実行またはファイル転送によるファイル操作」と「ライブラリオブジェクトによるファイル操作」を組み合わせて自動化処理を行なう場合は、「4.2.2.2. ホストと jobmngrd コンテナ間のファイル共有」と「4.2.2.3. ホストと kengine コンテナ間のファイル共有」を合わせて対処しておく必要があることに注意してください。 ##### 対策案１ 例えばそれぞれの対策案である「ホストとコンテナ間のファイル共有」を jobmngrd コンテナと kengine コンテナの両方に適用しておくことで、jobmngrd コンテナで実行されたコマンドによって書き出されたファイルと、kengine コンテナから呼び出される Python コードで読み込んで後続処理を行なう、といったことが可能になります。 ``` volumes: - /opt/kompira-shared:/kompira-shared ``` このとき、それぞれのコンテナがマウントするホスト側のボリュームは同じディレクトリ（この例では /opt/kompira-shared）になるようにしてください。 これで、jobmngrd コンテナと kengine コンテナがホストサーバを介してファイル共有できるようになりましたので、例えば以下のようにライブラリとコマンド実行によるファイル操作の連携が KE2.0 環境でもできるようになります。 ``` |input_data = "EXAMPLE-DATA"| # ライブラリでファイルを書き出して gzip コマンドで圧縮する [./fileio.file_write: "/kompira-shared/testdata", input_data] -> ["gzip -f /kompira-shared/testdata"] -> # 添付ファイルオブジェクトのフィールドにアップロードする upload(from_path="/kompira-shared/testdata.gz", to_object=./Package, to_field="attached2") -> # ライブラリでファイルを読み込んで、フィールドに保存されたデータと一致するかチェックする [zipped_data = ./fileio.file_read("/kompira-shared/testdata.gz", mode="rb", encoding=null)] -> assert(zipped_data == ./Package.attached2.data) ``` #### 4.2.2.5. クラスタ構成におけるノード間のファイル共有 前節まででホスト間とコンテナ間でのファイル共有はできるようになり、KE 2.0 系においてもシングル構成であればファイル処理が簡単に出来るようになりました。 しかしクラスタ構成の場合は、さらなる注意と対策が必要になります。 クラスタ構成の場合、ジョブフロープロセスはいずれかのノードの kengine コンテナ上で実行されて、ライブラリオブジェクトの呼び出しについては同じコンテナ上で行われます。一方で、ジョブフローからコマンド実行などのリモートジョブが呼び出されると、リモートジョブについては、いずれかのノードの jobmngrd コンテナ上で実行されることになります。 これは、ジョブフロープロセスの実行（ライブラリオブジェクトの呼び出しを含む）と、そこから呼び出されるコマンド実行などのリモートジョブが、異なるノード上で実行されることを意味します（たまたま同じノード上で実行される場合もあります）。 そのため、例えば同じファイルに対して複数のファイル操作を連携させている場合などで、それぞれが異なるノードで実行されると、片方ではファイルにアクセスできなかったり、ファイルが更新されていなかったり、と問題が生じる可能性があります。 ##### 対策案１ 例えばネットワークを介した共有ファイルシステムを準備して、クラスタを構成する各ホストサーバは同じネットワーク共有ディレクトリをマウントするようにしてください。KE 2.0 管理者マニュアルでは Swarm クラスタの構成例において、GlusterFS を利用して共有ディレクトリを準備しています。参考にしてみてください。 - https://fixpoint.github.io/ke2-admin-manual/setup/cluster/swarm/setup-glusterfs.html 共有ファイルシステムを GlusterFS 以外で構築することもできると思いますので、これはそれぞれの環境に合わせて準備するようにしてみてください。 ここでは各ホストサーバが `/mnt/gluster` という共有ディレクトリをマウントできている、という前提で説明します。 あとは、各コンテナがマウントとするボリュームの、ホスト側での場所として共有ファイルシステム上のディレクトリを指定すればよいことになります（ディレクトリは事前に作成しておいてください）。 ``` volumes: - /mnt/gluster/kompira-shared:/kompira-shared ``` このボリューム設定を jobmngrd コンテナと kengine コンテナに適用してデプロイすることで、クラスタ構成においてコマンド実行とライブラリ呼び出しが別ノード上で実行されたとしても、期待通りに動作するようになるはずです。ただし関連するファイル操作は同じ共有ディレクトリ上で行なうようにする必要があることには注意してください。 ### 4.2.3. マルチExecutor /Engine 化に伴う修正 #### 4.2.3.1. ジョブフロープロセスの並列動作と排他制御 KE 1.6 系までは複数のジョブフローを同時に実行したとしても、それらが並列に動作することはありませんでした。これは、以下のような内部動作によるものです。 複数のジョブフロープロセスを実行している状況でも、ある瞬間を見ると kompirad サービスの内部ではそのうちの１ジョブフロープロセスだけが実行されていて、他のジョブフロープロセスは実行可能状態として待機中となっています。kompirad サービスは短時間ごとに実行中のジョブフロープロセスを切り替えながら動作させることで、複数のプロセスが並行に動くように制御しています。この仕組みは単純である反面、マルチコア CPU のサーバを Kompira サーバとして用意して、複数のジョブフロープロセスを動作させてもその CPU リソースを使いきることが出来ない、といった制限にも繋がっていました。 一方、KE 2.0 系ではアーキテクチャが変更になり、ジョブフロープロセスの実行を担うコンポーネントが kompirad サービスから、kengine コンテナ内部の Executor という部位に変更になりました。この Executor は kengine コンテナ内部で最大でホストの CPU コア数だけ動作するように設計されています。これは、KE 2.0 系においては、複数のジョブフロープロセスがシステム上の Executor の合計数まで並列に実行できることを意味しています。（なお、KE 2.0 系においても、Executor 内部で複数のジョブフロープロセスが実行状態になることがありますが、これについては KE 1.6 系同様に短時間ごとの実行プロセス切り替えによる並行動作になります） ジョブフロープロセスが並列に動作できるなったことはメリットだけでなく、設計や実装に重要な注意点が加えられることになります。 ジョブフロープロセスの実行単位は「ジョブ」であり、実行プロセスの切り替えが起きるのは基本的にはこの「ジョブ」と「ジョブ」の間になります。例外的にいくつかのジョブでは、その内部で自らのプロセスを待ち状態に遷移することで、実行プロセスの切り替えが起きる場合もあります。この基本動作は KE 1.6 系も KE 2.0 系も同じです。 - KE 1.6 系では複数のジョブフロープロセスが並列に動作することがない、というのはこの実行単位である「ジョブ」がどの瞬間でも最大１つしか実行されないことを意味します。 - KE 2.0 系では複数のジョブフロープロセスが並列に動作することがある、というのはこの実行単位である「ジョブ」がある瞬間に2つ以上同時に実行されることがあることを意味します。 このような動作の違いから KE 2.0 系では、より注意深く排他制御を行なうようにすべき場合があります。例えば、複数のプロセスが同一オブジェクトを更新したり参照したりするような処理がある場合などは注意が必要です。 対策としては、クリティカルパス部分のジョブフローの「多重度を1にする」などが有効になります。ジョブフロープロセスの多重度制御はシステム全体で（クラスタ構成においてはノード間をまたいで）行なわれるため、簡単な排他制御の手段となります。 #### 4.2.3.2. 複数プロセスによる処理分担における spawn() の利用 KE 1.6 系および KE 2.0 系どちらにおいても、`fork` ブロックや `pfor` ブロックを使用することでジョブフローから子プロセス（親プロセスの複製）を生成することができます。その結果、KE 1.6 系では kompirad 内部で複数のプロセスが動作し、KE 2.0 系では kengine コンテナ内部の Executor 内部で複数のジョブフロープロセスが動作します。 これらはいずれも「4.2.3.1. ジョブフロープロセスの並列動作と排他制御」で説明したように、複数のジョブフロープロセスが KE 1.6 系では kompirad 内部で、もしくは KE 2.0 系では Executor 内部で、短時間で切り替わりながら並行動作していることになります。 複数の Executor が動作するように構成した KE 2.0 系であっても、親プロセスとそこから fork や pfor で生成した子プロセスからなる複数プロセスはすべて同じ Executor 内部で動作することになるため、それらのプロセスだけが実行中の場合は、ある Executor に負荷が集中してシステム全体の CPU リソースを効率的に使えないことになります。これは fork および pfor が KE 1.6 系以前のアーキテクチャに合わせて設計された機能であって、KE 2.0 系にも互換性をもって利用できるように移植されたための制約とも言えます。 そこで KE 2.0 では、**新しいアーキテクチャに合わせて `spawn()` 組み込み関数が追加されました**。 この新しい `spawn()` はジョブフローやパラメータ引数などを与えると、新しいジョブフロープロセスを生成して指定したジョブフローを実行します。spawn() で生成されるジョブフロープロセスはいずれかの kengine コンテナ上のいずれかの Executor 上で実行されることになります（実行する kengine や Executor を指定することは出来ません）。 ちなみに、この spawn() の動作は、ブラウザを使ってジョブフロー詳細画面でパラメータを入力して「実行」ボタンを押下することや、REST-API でジョブフローオブジェクトを指定した `POST <ジョブフローパス>.execute` を呼び出すのと同じです。 KE 2.0 系において、システム全体のリソース使用率の向上や負荷分散を狙う場合は、fork や pfor を使って複数プロセスに処理を分割している箇所を、spawn() を使って新たなプロセスでジョブフローを開始するように設計と実装を見直すことができないか、検討してみてください。 このとき fork や pfor と spawn() の以下のような違いを理解しておいてください。 - fork や pfor を呼び出したプロセスは生成した子プロセスと親子関係を持ちますが、spwan() で生成したプロセスは親子関係を持ちません。 - 新しいプロセスの parent プロパティに違いが現れます。 - プロセス一覧画面での表示のされ方が違います（親子関係がある場合は、子プロセスは親プロセスの「子プロセス一覧」に表示されます）。 - fork や pfor は親プロセスの複製を生成しますが、spawn() は完全に新しいプロセスを生成します。 - fork や pfor で生成した子プロセスは親プロセスと共有するメモリがあり、親プロセスが持つ変数を参照することができます。 - spawn() で生成した新しいプロセスは他のプロセスと共有するメモリは無く、呼び出し元プロセスが待つ変数の参照などはできません。 - fork や pfor は子プロセスの終了を待ちますが、spawn() は生成したプロセスの終了を待ちません。 - fork や pfor は子プロセスや親プロセスと同じ kompirad 内部で動作しますが、spawn() で生成したプロセスは呼び出し元と同じ Executor 上で動作するとは限りません。 ## 4.3. システム構成変更に伴う移行作業 - SMTP サーバ設定の必須化 - ログ出力設定の検討 - 外部連携の検討 - kompira_sendevt によるメッセージ送信 - クラスタ構成の場合の検討 - ロードバランサー導入検討 - マルチエンジン化に伴うフェイルオーバ対策 ### 4.3.1. SMTP サーバ設定の必須化 KE 1.6 系まではデフォルトの SMTP サーバを設定していない場合でも Kompira からメールを送信することができました。これには `mailto()` ジョブによるメール送信や、ジョブフロー異常終了時の自動メール送信（監視モードを設定している場合）も含みます。これは SMTP サーバを設定していなくても、KE 1.6 系では Kompira サーバにデフォルトでインストールされる sendmail サービスによってメールが送信されていたためです。 一方で、KE 2.0 系ではデフォルトで sendmail サービスは構成されないため、SMTP サーバを設定しないと Kompira からメールを送信することが出来ません。（Kompira から一切メールを送信しない場合は実際的な問題はありません） 移行元システムで SMTP サーバを設定していた場合は、移行後の KE2.0 系でも同様に SMTP サーバを設定してください。 移行元システムで SMTP サーバを設定せずに sendmail によるメール送信を利用していた場合は、移行時には Kompira からアクセスできる外部 SMTP サーバを用意して、 Kompira 上で以下のオブジェクトに SMTP サーバ情報を設定するようにしてください。 ``` /system/smtp_servers/Default ``` 事前に設定を済ませておくことで、デフォルトでこの SMTP サーバを介してメールが送信されるようになります。 ### 4.3.2. ログ出力設定の検討 KE 2.0 系での Kompira のログ出力の仕組みが KE 1.6 系までとは異なっていますので、その違いを理解したうえで、必要であればログ出力設定やシステム構成をカスタマイズすることを検討してみてください。 #### 4.3.2.1. ログの出力先の確認 KE 1.6 系までは Kompira 本体のログは標準でサーバ上の `/var/log/kompira/` ディレクトリ配下にファイルとして出力されます。 KE 2.0 系では出力されるログの内容自体は 1.6 系とほぼ同等ですが、ログの出力先は 1.6 系とは異なっています。コンテナログ、ボリュームログ、プロセスログ、監査ログそれぞれで出力先が異なりますので、KE 2.0 管理者マニュアルで確認しておいてください。 - https://fixpoint.github.io/ke2-admin-manual/management/logging/index.html #### 4.3.2.2. コンテナログ出力ドライバの変更 KE 2.0 系において、コンテナログの出力はデフォルトでは Docker の `local` ロギングドライバを使用して出力されます。このとき出力されたログは Docker サービスによって管理・記録されるため、ログの内容を参照するには例えば以下のように docker logs コマンドを用いる必要があります。 ``` $ docker logs $(docker ps -q -f name=kengine) ``` この状態ではサービスごとのログをファイル名で指定して参照するということが出来ないと分かります。これは例えば「監視システムによって Kompira のログ文字列を監視したい」といったときに、監視対象をファイル名で指定する必要がある場合に問題になります。 ログを監視したいといった目的のために、ログ出力はファイルに直接記録されることが望ましい、という場合は、使用する Docker のロギングドライバを別のものに変更することを検討してみください。 ##### 対策案1: fluentd へのログ出力 Docker のロギングドライバに "fluentd" を使用すると、各コンテナのログを指定した fluentd サーバに送信することが出来ます。 この方式の場合、各コンテナからのログを受け取って記録する fluentd サーバの準備が必要になります。fluentd サーバは KE 2.0 の各コンテナから IP リーチャブルで TCP ポート 24224 でアクセスできる必要があります。以下では Red Hat 系 OS に fluentd サーバを準備する最低限の手順例を示します。ご利用になるサーバに合わせて手順は読み替えて下さい。 (1) ログを記録するサーバに fluentd をインストールしてください。 ``` # curl -fsSL https://toolbelt.treasuredata.com/sh/install-redhat-fluent-package5.sh | sh ``` (2) ke2-docker にある fluentd.conf をダウンロードして /etc/fluentd.conf に配置してください。 ``` # curl -L https://raw.githubusercontent.com/fixpoint/ke2-docker/refs/heads/main/configs/fluentd.conf -o /etc/fluent/fluentd.conf ``` (3) /var/log/kompira ディレクトリを作成してください。 ``` # install -o fluentd -g fluentd -d /var/log/kompira ``` (4) fluentd サービスを起動してください。 ``` # systemctl start fluentd ``` 次に KE 2.0 側でのログ出力の設定を変更します。ロギングドライバの指定は各構成の docker-compose.override.yml で行います。docker-compose.override.yml の `x-logging:` という項目の部分を以下のように書き換えてください。 ``` x-logging: &default-logging driver: fluentd options: tag: "docker.{{.Name}}" fluentd-address: ":24224" ``` ここで、`` の部分は上で準備した fluentd サーバのIPアドレスを指定するようにしてください。 この設定を適用してデプロイすると、各コンテナのログは `fluentd-address:` で指定した fluentd サーバに送信されます。上で準備した fluentd サーバは各コンテナからのログを受け取ると、ke2-docker に含まれたサンプルの fluentd.conf に設定されたルールに従って、/var/log/kompira/ 配下にコンテナごとにログファイルとして出力しているはずです。 ``` # LANG= ls -l /var/log/kompira/ total 152 -rw-r--r--. 1 fluentd fluentd 8615 Dec 27 15:11 jobmngrd.20241227.log -rw-r--r--. 1 fluentd fluentd 18817 Dec 27 15:11 kengine.20241227.log -rw-r--r--. 1 fluentd fluentd 13259 Dec 27 15:11 kompira.20241227.log -rw-r--r--. 1 fluentd fluentd 12544 Dec 27 15:11 nginx.20241227.log -rw-r--r--. 1 fluentd fluentd 83085 Dec 27 15:11 rabbitmq.20241227.log -rw-r--r--. 1 fluentd fluentd 2426 Dec 27 15:28 redis.20241227.log ``` サーバで動作している fluentd サービスや、Docker のロギングドライバーとしての fluentd にも、それぞれ様々な設定オプションなどがありますので、目的に合わせて適切な構成になるように調整してみてください。 #### 4.3.2.3. ログローテーション KE 1.6 系までは Kompira のログはデフォルトでローテーションする設定になっていました（周期・世代指定は不可）。一方、KE 2.0 系では Kompira のログローテーションは次のように変更されました。 - プロセスログと監査ログ - 環境変数でローテーション制御などの設定を指定できるようになりました。KE 2.0 管理者マニュアルの以下を参考にしてみてください。 - https://fixpoint.github.io/ke2-admin-manual/config/system/environment.html - それ以外のログ - Kompira 本体ではログ出力の制御自体を行なっていないため、Docker およびロギングドライバの設定に依存します。 プロセスログと監査ログ以外のログファイルの柔軟なローテーション制御が必要な場合は、logrotate を導入してローテーションさせるようにしたり、ロギングドライバのオプションなどで調整することを検討してください。 ### 4.3.3. 外部連携の検討 #### 4.3.3.1. kompira_sendevt によるメッセージ受信 v2.0 で外部から kompira_sendevt によるメッセージ送信を行う場合、Kompira サーバ側で次の2つの準備が必要になります。 ##### (1) AMQP ポートの公開 サンプルで提供している docker-compose.yml では、rabbitmqコンテナの AMQP(5672番) ポートは公開していないため、必要に応じて以下の行を ke2/services/rabbitmq.yml に追加します。 ``` ports: - "5672:5672" ``` ##### (2) RabbitMQの接続ユーザー作成 デフォルトの guest ユーザーは外部からの接続を受け付けないため、以下のコマンドで新たに接続用のユーザーを作成します。（以下ではユーザー名＝パスワードkompira を想定） ``` $ docker compose exec rabbitmq rabbitmqctl add_user kompira kompira $ docker compose exec rabbitmq rabbitmqctl set_permissions -p / kompira ".*" ".*" ".*" ```