プラグイン: 最小構成 (Windows)

想定読者: Windowsエンドポイントに常駐型の管理プラグインを登録する統合担当者。

本例は、Windows向け実行ファイルに対して妥当な最小限のプラグインJSONを示します。autoStart を有効にし、主たるMQTTサブスクリプション、監視と自動再起動、および KeeperLogger へのパブリッシュ許可を含みます。デプロイ前にプレースホルダを実際の値に置き換え、出発点としてご利用ください。LinuxおよびmacOS向けは、プラグイン: 最小構成 (Linux) およびプラグイン: 最小構成 (macOS) をご参照ください。

コンポーネントがスケジュールで動作して終了するだけで常駐しない場合はジョブタスク向けです。まずはジョブ: 最小構成 (Windows) をご参照ください。

プラグインのJSON

{
  "id": "MyBridge",
  "name": "My Bridge",
  "description": "Long-running bridge component.",
  "version": "1.0.0",

  "pluginType": "Executable",
  "executablePath": "bin/MyBridge/MyBridge.exe",
  "supportedPlatforms": ["Windows"],

  "Subscription": {
    "Topic": "MyBridge",
    "Qos": 2,
    "CleanSession": true
  },

  "metadata": {
    "mqttRole": ["subscriber", "publisher"],
    "mqttTopics": {
      "publish": ["KeeperLogger"],
      "subscribe": ["MyBridge", "MyBridge/Commands/+"]
    }
  },

  "startupPriority": 60,
  "autoStart": true,
  "executionContext": "Service",
  "requiresMonitoring": true,
  "autoRestart": true
}

変更する箇所

フィールド

内容

id

安定した一意の識別子。プラグインのキーとして /api/PluginSettings/{id} に使われ、ファイル名とも一致させます ("id": "MyBridge" なら MyBridge.json)。デプロイ後に id を変える場合は移行手順を管理者と調整したうえで実施してください。変更すると、旧IDに紐づく設定は引き継がれません。

name

ログおよび管理画面に表示する名称

version

バイナリのセマンティックバージョン。診断と変更追跡のため、リリースごとに更新します。

executablePath

エージェントルートからの相対パス、または絶対パス。Windowsでのエージェントのデフォルトルートは C:\Program Files\KeeperPrivilegeManager のため、bin/MyBridge/MyBridge.exe は C:\Program Files\KeeperPrivilegeManager\bin\MyBridge\MyBridge.exe に解決されます。

Subscription.Topic

当該プラグインの主たるMQTTトピック。慣例としてプラグインの id を使います。エージェントに登録された全プラグインの間で一意である必要があります。

metadata.mqttTopics.publish

バイナリがパブリッシュするすべてのMQTTトピック。ログメッセージを出す場合は KeeperLogger を含めます。その他の出力トピックもここに列挙します。ブローカーが実行時にこの一覧を強制します。

metadata.mqttTopics.subscribe

主たる Subscription.Topic 以外にバイナリがサブスクライブするすべてのトピック。Commands/+ パターンはコマンド形式トピックの慣例です。使わない場合は置き換えるか削除します。

startupPriority

他プラグインとの起動順。小さいほど先に起動します。他のカスタム構成要素への依存がないカスタムプラグインでは、60 を妥当なデフォルトにできます。

動作の要点

pluginType: Executable は、オーケストレーターにバイナリを子プロセスとして起動するよう指示します。単体実行ファイル向けの正しいタイプです。

executablePath はプラグイン用ディレクトリではなくエージェントルートからの相対です。bin/MyBridge/MyBridge.exe は Plugins/ ツリーの外にバイナリを置く例で、プラグイン関連ディレクトリ内の実行ファイルに適用される厳しい証明書パス検査を避けられます。デプロイレイアウトがこの慣例に合わない場合は絶対パスを使います。

Subscription はオーケストレーターが当該プラグインを識別するために使う主たるMQTTトピックです。失われたり重複してはならないコマンドには Qos: 2 を設定します。CleanSession: true は多くのプラグインで妥当で、再接続時にブローカーが前セッションのキュー済みメッセージを破棄し、再生しないことを意味します。

metadata.mqttTopics は、バイナリが実際にパブリッシュ／サブスクライブする内容と正確に一致させる必要があります。ブローカーが実行時にこれらの一覧を強制し、宣言外のパブリッシュやサブスクライブは拒否されます。ジョブタスクとは異なり、プラグインにジョブレベルの別ブロック mqttTopics はなく、宣言はすべて metadata 配下に置きます。

autoStart: true により、エージェント起動時にオーケストレーターがプラグインを起動します。オンデマンドやジョブによる起動のみにしたい場合は false にします。そのパターンはプラグイン: 手動起動をご参照ください。

requiresMonitoring: true と autoRestart: true を併用すると、オーケストレーターがプロセスを監視し、異常終了時に再起動します。常駐が必須の本番プラグインでは両方を有効にします。意図的な終了条件がある場合は、ログでクラッシュと区別できる終了コードにします。

executionContext: Service はプラグインをエージェントのサービスアカウントで実行します。対話的なユーザーセッションを要しないバックグラウンド構成要素向けです。

デプロイ前に

バイナリに署名する: Windowsではプラグイン用バイナリがジョブタスク用より厳しい信頼チェックの対象になります。Authenticode証明書で署名し、必要に応じて appsettings.json の Settings:AlternativeSignatures にサムプリントを追加します。
バイナリを配置する: プラグイン登録前に executablePath が解決する場所へ置きます。
JSONファイルを配置する: {AgentRoot}\Plugins\MyBridge.json に置き、ファイル名を id と一致させます。
管理者と手順をすり合わせる: JSONを置いてエージェントを再起動するのが一般的ですが、パッケージングやポリシー要件は環境により異なります。
エージェントサービスを再起動する: 両方のファイルを配置したあと再起動し、オーケストレーターが新しい登録を読み込みます。

検証

エージェント再起動後、ログでプラグイン名を確認して起動に成功したことを確かめます。続いて、バイナリからの KeeperLogger パブリッシュがオペレーター向けのログ画面に表示されることを確認し、MQTTの疎通を裏づけます。

プラグインの実効設定を読み取る例です。

Invoke-RestMethod -Method Get `
  -Uri "https://127.0.0.1:6889/api/PluginSettings/MyBridge" `
  -Certificate $pluginClientCert

この呼び出しにはプラグイン階層の認証が必要で、エージェントが起動したプロセスからでなければなりません。任意のスクリプトからではなく、プラグインバイナリ内の起動時に実行し、設定取得までの経路が正しく機能しているか確認します。

前へジョブ: イベントトピック付き次へプラグイン: 最小構成 (Linux)

最終更新 3 日前