統合の概要
本ページでは、コードやJSONを書く前に全体像をつかめるよう、KEPM統合の背後にある概念と構成要素を説明します。統合機能のランディングページをまだ読んでいない場合は、そちらから始めてください。2つの統合パターンの定義と、着手前にデプロイチームから確認しておくべき事項がまとまっています。
主な用語
以下の用語がKEPMでどう使われるかを押さえておくと、各ガイドを読むときの混乱を防げます。
ジョブ — エージェントの Jobs/ ディレクトリ配下に {job-id}.json として保存されるJSONドキュメントです。ジョブは、いつ 何かを走らせるか (スケジュール、起動イベント、名前付きイベントトピック) と、何を 走らせるか (1つ以上のタスク) を定義します。カスタム実行ファイルのスケジュール実行と駆動の主たる手段です。
タスク — ジョブ内の1ステップです。実行ファイルまたはスクリプトを指し、実行方法 (ExecutionType)、引数、タイムアウト、失敗時の扱いを指定します。多くのカスタム統合ではジョブあたりタスクは1つです。
プラグイン — Plugins/{PluginId}.json に登録され、エージェントが第一級のプロセスとして管理するコンポーネントです。プラグインはエージェント制御のライフサイクル (起動、監視、再起動) を持ち、独自のアイデンティティに紐づくMQTTトピックを購読します。ジョブタスクのバイナリとは別概念です。エージェント横に配置しただけでは、実行ファイルが自動的にプラグインになるわけではありません。
KeeperLogger — 組み込みのエージェントコンポーネントで、MQTTトピック KeeperLogger を購読し、受信メッセージをエージェントのログパイプラインに書き込みます。実行ファイルはそのトピックへ構造化JSONをパブリッシュし、エージェントがメッセージをオペレーター向けのログ経路へ渡します。カスタムジョブタスクがプラットフォームへ結果を返す主な方法です。
MQTTブローカー — エージェントがループバックインターフェース上で動かすローカルメッセージブローカーです (デフォルトは 127.0.0.1:8675、TLS)。タスクのバイナリを含むローカルコンポーネントが接続し、パブリッシュと購読を行います。アクセスはプロセス信頼で制御され、エージェントが起動した実行ファイル、または明示的に許可リストに載った実行ファイルだけが接続できます。
プロセス信頼 — どのローカルプロセスがMQTTブローカーに接続し、プラグイン階層のHTTPSエンドポイントを呼び出せるかをエージェントが決める仕組みです。ジョブランナーがバイナリを起動すると、そのプロセスは直ちに登録され、バイナリからのMQTTおよびHTTPS呼び出しが許可されます。バイナリが別の経路で起動している場合 (手動、スクリプト経由など) は、代わりに証明書チェックに合格する必要があります。詳細はカスタムジョブ統合ガイドをご参照ください。
統合の流れ
以下の流れは、ジョブがデプロイされてから、ログ行がオペレーターの画面に現れるまでの動きです。
エージェントが関所です。 バイナリがプロセス信頼、MQTTアクセス、実行時設定を得るのは、エージェントが起動したからであり、バイナリ単独の最初の動作によるものではありません。
ブローカーアドレスをハードコードしません。 バイナリは起動時にプラグイン設定をHTTPSでエージェントに問い合わせ、エージェントが現在の broker.host と broker.port を返します。
ログは標準出力ではなくMQTTを経由します。 バイナリは KeeperLogger MQTTトピックへ構造化JSONをパブリッシュします。以降の配信はエージェントが担います。
MQTTの権限はジョブJSONで決まります。 バイナリがパブリッシュできるのは、ジョブの mqttTopics.allowedPublications に明示されたトピックに限られます。ブローカーが許可を強制し、権限の継承や暗黙の付与はありません。
ジョブとプラグイン
2つの統合パターンは同じエージェントと同じMQTTブローカーを共有しますが、目的は根本的に異なります。
ジョブを選ぶ場合
スケジュールまたはエージェント起動時にツールを実行する
schedule.intervalMinutes および/または eventType: Startup の events エントリを定義する
KeeperLoggerへログを送る
ジョブに mqttTopics.allowedPublications: ["KeeperLogger"] を設定する
複数OSをサポートする
osFilter を設定し、各プラットフォームでは一致するタスクだけが実行されるようにする
バイナリへ実行時設定を渡す
tasks[].arguments の {KeeperApiBaseUrl} など変数置換を使う
プラグインのオーバーヘッドなしでバイナリを配布する
Jobs/bin/{CommandName}/ に配置する。プラグイン用のJSONは不要
ジョブタスクのバイナリは常駐である必要はありません。想定パターンは、起動して処理し、意味のある終了コードで終了することです。エージェントは終了コードを記録し、出力を取り込み、次に進みます。
プラグインを選ぶ場合
プロセスを常時実行し続ける
プラグインJSONで autoStart: true と requiresMonitoring: true を指定できる
失敗時にエージェントにプロセス再起動してほしい
プラグインJSONで autoRestart: true を設定する
名前付きの永続アイデンティティとしてMQTTトピックに購読する
プラグインは主な Subscription を持ち、独自のトピック名前空間を持つ
プラグインID単位で取得できるコンポーネント別設定を置く
GET /api/PluginSettings/{yourPluginId} でプラグイン設定を読める
エージェントのネイティブ部品のように振る舞うコンポーネントを出荷する
パッケージ、署名、ライフサイクルはエージェント同梱コンポーネントと同等の前提で扱われる
両方を使う場合
両方が必要になるのは、ライフサイクルが明確に2つに分かれるときだけです。常時オンで監視されるプラグインとして登録された常駐デーモンと、別バイナリによる定期処理を行うスケジュールジョブが別々に存在するケースです。
同一実行ファイルをプラグインとジョブタスクの両方に登録しないでください。重複プロセス、MQTTクライアントIDの衝突、どの設定パスがバイナリの設定の主であるかの曖昧さを招きます。
クイックリファレンス
ジョブタスクに Plugins/{id}.json は必須か
いいえ。ジョブには Jobs/{id}.json とデプロイ済みバイナリだけで足ります
ジョブタスクはMQTTへパブリッシュできるか
はい。ジョブに mqttTopics.allowedPublications を宣言すれば可能です
ジョブタスクはHTTPSでプラグイン設定を呼べるか
はい。エージェントが起動した場合 (プラグイン階層の認可)
プラグイン登録が必要なのはどんなときか
エージェント管理のライフサイクル、永続的なMQTT購読、プラグインスコープの設定のいずれかが必要な場合に限ります
エージェントがプロセスへ渡すもの
エージェントがバイナリをジョブタスクとして起動するとき、以下の環境変数を設定します。ただし、ジョブで mqttTopics に許可されたパブリケーションまたは購読が1つ以上ある場合に限ります。
KEEPER_JOB_ID
ジョブJSONの id フィールド
MQTTクライアントIDを組み立てるときに必須
KEEPER_JOB_NAME
ジョブJSONの name フィールド
ログメッセージや診断に便利
tasks[].arguments に含めた場合、{KeeperApiBaseUrl} は環境変数ではなく置換後の引数値としてバイナリに渡されます。プラグイン設定のHTTPS呼び出しのベースURLとして使います。
エージェントは broker.host、broker.port、MQTT接続の詳細を環境変数として注入しません。バイナリは実行時にプラグイン設定から読み取る想定です。
このあと読むドキュメント
スケジュールまたはイベント駆動のツール (最も一般的なケース) には、カスタムジョブ統合ガイドをご参照ください。バイナリのビルドとデプロイ、ジョブJSONの作成、MQTT接続と構造化ログのパブリッシュまで、手順を一通り扱います。
管理対象の常駐コンポーネントの場合は、カスタムプラグイン統合ガイドをご参照ください。
ジョブのデプロイをスクリプト化する準備ができたとき、またはバイナリ内からプラグイン設定を呼び出すときは、HTTPリファレンスにエンドポイント、認可階層、リクエスト形式がまとまっています。
最終更新