ACC(Agent Client Collector)をDockerに導入して実機検証してみた

はじめに

PDI環境において、ACC(Agent Client Collector)をdockerコンテナに追加して実機検証しました。

やってみると、接続に至るまでに Docker 特有の MID アップグレード失敗、「認証失敗はインスタンスに届かない」という構造など、ドキュメントだけでは分からない知見が多かったので記事にします。

想定読者

• ACC の導入・トラブルシュートをする人
• MID Server を Docker で動かしたい人
• 「エージェントがつながらない」の切り分けを体系的にやりたい人

検証環境のポンチ絵

Docker compose で 1 サブネットに 4 コンテナ。Mac(Apple Silicon)上ですが、ACC 6.6.1 は Ubuntu ARM64 のネイティブ deb が公式提供されている(2026-07 リリースで追加)ため、エージェントは Rosetta なしで動きます。

ポイントは矢印の向きです。
MIDサーバ→インスタンスは MIDサーバ が外向きに HTTPS でポーリング、ACC→MIDサーバ はエージェントが外向きに WebSocket を張る。インスタンスからもMIDサーバからも「入ってくる」通信はエージェント方向に存在しません
(だから ACC はファイアウォール内のサーバーに強い)。

MID Server と ACC の差異

同じ「インスタンスの手足」でも役割がまったく違います。

観点	MID Server	ACC
実体	Java (JVM + Jetty)、対象環境に少数配置	Go 製の軽量エージェント(Sensu ベース)、対象サーバー全台に配置
通信	インスタンスへ HTTPS ポーリング(ecc_queue)	MIDサーバ へ WebSocket(wss://mid:8800/ws/events)
認証	インスタンスのユーザー(mid_server ロール)	MID がローカルで検証する API キー(api_key テーブルで発行)
データ収集	リモートから資格情報でログイン(Discovery/Orchestration)	ローカルで check を実行して push(資格情報の配布不要)
対象への要件	SSH/WinRM 等を開ける必要あり	外向き wss 1 本のみ
アップグレード	インスタンスから自動配布	手動 or 配布ツール(deb/rpm/msi)
主用途	Discovery, 統合, Orchestration	ACC-V(可視化), ACC-M(監視), ACC-L(ログ)

要するに **ACC は「MID の子」**です。インスタンスと直接は話さず、認証も MID 上で完結します。この構造が後述の「監視の非対称性」を生みます。

つながるまでの落とし穴(実録)

落とし穴1: MID Web Server を作っただけでは 404

MID Server > Extensions > MID Web Server でコンテキストを作成し、ポート 8800 で SSL 起動まで確認。しかしエージェントは:

[ERROR] [agent] [handshake failed with status 404: ] reconnection attempt failed
to the url: wss://172.28.100.10:8800/ws/events, using api-key authentication failed

404 = /ws/events エンドポイント自体が未登録です。MID サーバーレコードの関連リンク「Setup ACC Listener」を実行して初めて WebSocket ハンドラが載ります(KB2612489 のパターン)。エラーメッセージが「authentication failed」を含むので認証問題に見えますが、404 のうちは鍵以前の問題です。

ちなみに証明書エイリアスは空でOKでした。MID Unified Keystore の既定鍵(defaultsecuritykeypairhandle)で Jetty が SSL 起動します。

落とし穴2: Docker の MID は自動アップグレードで死ぬ(2つの理由で)

検証中にインスタンスが Patch10 に上がり、MID の自動アップグレードが走って2つの Docker 特有問題を踏みました。

1. entrypoint が mid.sh console(フォアグラウンド)だと、アップグレードが JVM を止めた瞬間にコンテナごと終了し、アップグレード処理が途中で殺される → 永遠にアップグレードループ。mid.sh start(デーモン)+ tail -F でコンテナを存命させる方式に変更
2. overlayfs はイメージ層由来のディレクトリを rename できない(EXDEV)。アップグレーダが /opt/agent/bin → bin_old のリネームで 5 回リトライして失敗し続ける → /opt/agent を named volume に移設して解決

07/18/26 00:57:17 | INFO    | Renaming the folder `/opt/agent/bin` to `/opt/agent/bin_old`. File rename attempt (4/5).
07/18/26 00:57:17 | WARNING | Renaming folder `/opt/agent/bin` failed

Docker で MID を組む人は、最初から ①デーモン+tail 型 entrypoint ②/opt/agent をボリュームに の2点を入れておくことを勧めます。

認証失敗 vs 成功: ログの出方

誤った API キー(認証失敗)

エージェント側 /var/log/servicenow/agent-client-collector/acc.log:

[ERROR] [agent] [handshake failed with status 401: ] reconnection attempt failed
to the url: wss://172.28.100.10:8800/ws/events, using api-key authentication failed,
validate URL is reachable and authentication is valid

MID 側 agent/logs/agent0.log.0:

ERROR (MidWebServer-192) [ApiKeyAuthenticator:95] ERROR in web server API Key
authenticator: invalid API Key

• 404 → リスナー未設定(Setup ACC Listener を忘れている)
• 401 → リスナーは生きていて鍵が違う

失敗が続くとエージェントは 1 分 → 10 分とバックオフしていきます。「キーを直したのにつながらない」ときは、このバックオフ待ちの可能性もあります(再起動すれば即時再試行)。

正しい API キー(成功)

[INFO] [agent] successfully connected to the url: "wss://172.28.100.10:8800/ws/events"
[INFO] [keepalive] [agent] [acc-target-01] [...] sending event to backend
[INFO] [agent] keepalive response received from the backend.

MID 側:

INFO (Monitoring.KeepAlive.1) [ClientStateRegistry:99]
[session=1][agent=acc-target-01][remote=172.28.100.23] agent registered for communication

インスタンスの Agent Client Collector > Agents に acc-target-01 が Up で登場します。

監視方法: どこに何が出る(出ない)か

一番大事な構造がこれです:

API キー認証は MID の Jetty で完結する。拒否された接続はインスタンスに到達しない。つまり「認証失敗」はインスタンスのどのログにも出ない。

インスタンス側で見える場所と役割の整理:

場所	テーブル	見えるもの
System Logs > ECC Queue	ecc_queue	ACC WebSocket Endpoint の稼働統計・エージェント経由データの流れ(name に "ACC" でフィルタ)
MID Server > Servers > 対象 > Logs	ecc_agent_log	MID がエスカレーションしたログ。認証エラーは既定では上がってこない
MID Server > Servers > 対象 > Issues	ecc_agent_issue	MID が検知した異常の起票
ACC > Agents → 対象レコード	sn_agent_cmdb_ci_agent	Up/Down、Last keepalive。関連リンクからエージェントの acc.log を取り寄せ(Collect Agent Log)も可能
System Logs > All	syslog	sn_agent アプリのサーバーサイドエラー

したがって、運用で認証失敗を検知したい場合の現実解は:

1. 正面から: MID ローカルの agent0.log を外部のログ基盤で監視(ApiKeyAuthenticator の ERROR を拾う)
2. 裏から: 「登録されるはずのエージェントが Agents に現れない/Down のまま」をインスタンス側で監視する(こちらは標準機能だけで可能)

ECC Queue

まとめ

• ACC は「MID の子」— 認証も通信も MID で完結し、認証失敗はインスタンスに届かない。監視設計はこの非対称性を前提に
• つながらないときは HTTP ステータスで切り分け: 404=Setup ACC Listener 忘れ、401=API キー違い
• Docker で MID を動かすなら、自動アップグレード対策として デーモン型 entrypoint + /opt/agent のボリューム化 を最初から
• ACC 6.6.1 で Ubuntu ARM64 がネイティブサポートされ、Apple Silicon の Docker でもエージェントが素直に動くようになった