1. コールバックプラグインの位置づけ
コールバックプラグインとは、Playbook 実行中に発生する「イベント」にフックして、独自の挙動を追加できる仕組みです。(Ansible ドキュメント)
- 何ができるか： 画面出力のカスタマイズ、実行ログの外部 DB 保存、Slack/Teams への通知、実行時間の詳細レポート作成など。
-
仕組み：
CallbackBaseクラスを継承したCallbackModuleクラスを定義し、v2_で始まるメソッド（フック）をオーバーライドします。(Ansible ドキュメント)
2. stdout_callback と callbacks_enabled の違い
ここが最も混乱しやすいポイントです。役割を「メイン出力」か「追加機能」かで使い分けます。(Ansible Documentation)
| 設定項目 | 役割 | 指定数 | 主な用途 |
|---|---|---|---|
| stdout_callback | 画面表示の主役 | 1つのみ | 標準出力を JSON 化する、1行にまとめるなど。 |
| callbacks_enabled | 裏方の追加機能 | 複数可能 | 実行時間の計測(timer)、ログ収集、外部通知など。 |
重要な落とし穴
-
stdout を変えたい場合： プラグイン内で
CALLBACK_TYPE = 'stdout'と宣言し、stdout_callbackで 1 つ選ぶ必要があります。(Ansible Documentation) -
追加機能（通知など）の場合：
CALLBACK_TYPE = 'notification'とし、callbacks_enabledにリストアップします。notification 系をstdout_callbackに書いても “主役” にはなれません。 -
互換性：
callbacks_enabledは比較的新しい呼び名で、古いドキュメントではcallback_whitelistと表記されています（概念は同じです）。(Ansible Documentation)
3. 配置場所（どこに置けば Ansible が見つけるか）
A) プロジェクトローカル（開発・テストに最適）
Playbook と同じ階層に callback_plugins/ ディレクトリを作成し、その中に .py ファイルを置きます。(Ansible ドキュメント)
- または
ansible.cfgのcallback_plugins（検索パス）に追加して管理します。
B) Collection 内（再利用・配布向き）
collections/ansible_collections/<namespace>/<collection>/plugins/callback/<plugin>.py
- FQCN（Fully Qualified Collection Name） で参照できるため、組織内での共有や CI 配布に非常に強いです。(Ansible ドキュメント)
4. 最小実装テンプレート（コピペ用）
以下は、イベントを受けて標準出力に情報を表示する最小限の骨格です。
# plugins/callback/my_callback.py
from __future__ import annotations
from ansible.plugins.callback import CallbackBase
DOCUMENTATION = r"""
name: my_callback
type: notification
short_description: イベントを標準出力に表示するサンプル
description:
- タスクの開始や結果を独自フォーマットで表示します。
options: {}
"""
class CallbackModule(CallbackBase):
CALLBACK_VERSION = 2.0
CALLBACK_NAME = "my_callback"
CALLBACK_TYPE = "notification" # 画面表示を完全に入れ替えるなら "stdout"
def v2_playbook_on_start(self, playbook):
# self._display.display を使うのが推奨です（stdout管理との整合性のため）
self._display.display("--- [my_callback] Playbook Execution Started ---")
def v2_runner_on_ok(self, result):
host = result._host.get_name()
task_name = result._task.get_name()
self._display.display(f"[SUCCESS] {host} : {task_name}")
def v2_runner_on_failed(self, result, ignore_errors=False):
host = result._host.get_name()
msg = result._result.get('msg', 'No error message')
self._display.display(f"[FAILED] {host} : {msg}")
def v2_playbook_on_stats(self, stats):
self._display.display("--- [my_callback] Playbook Finished ---")
-
CALLBACK_VERSIONとCALLBACK_NAMEは 2.0+ のプラグインで必須です。(Ansible ドキュメント)
5. 有効化（ansible.cfg の設定要点）
3.1 追加コールバック（stdout 以外）を有効化
近年のドキュメントでは callbacks_enabled を使います。(Ansible ドキュメント)
[defaults]
# (推奨) 追加で有効化する callback
callbacks_enabled = timer, my_namespace.my_collection.my_callback
# (旧来の設定) callback_whitelist = timer, ...
3.2 stdout を置き換える（見た目を変える系）
stdout_callback で 1 つだけ指定します。(Ansible ドキュメント)
[defaults]
stdout_callback = my_callback
6. 実装時のチェックリスト（事故防止）
-
PII/秘密情報の保護
result._resultにはタスクの戻り値がすべて含まれます。no_log: trueが設定されているタスクの情報を誤ってログへ出さないよう注意が必要です。 -
パフォーマンスへの影響
大量の出力や重い外部通知は実行速度に直結します。必要ならv2_playbook_on_statsで最後にまとめて集計して出力します。 -
例外処理
コールバック自体の障害で Ansible 本体を停止させないよう、最低限のエラーハンドリングを検討してください。 -
暗黙タスクの取得
meta タスクなども取得したい場合は、__init__でself.wants_implicit_tasks = Trueを設定します。(Ansible ドキュメント)
7. さらに詳しく知るために
最も確実な一次情報は、Ansible 本体のソースコード（lib/ansible/plugins/callback）を参照することです。(Ansible ドキュメント)