AnsibleのCallback Plugin設計入門｜実行結果をJSON出力・Slack通知・ARAで可視化する方法

この記事のポイント

・Callback PluginはPlaybook実行イベントを受け取る拡張点。ansible.cfgで有効化できる
・profile_tasksで各タスクの実行時間を計測してボトルネックを特定できる
・community.general.slackでPlaybook完了時にSlackチャンネルへ通知できる
・ARAはPlaybook実行履歴をDBで管理するOSSで、チーム運用の標準ツールとして使われている

# Playbook実行時のCallback Pluginの呼び出しフロー（概念図）
ansible-playbook site.yml を実行
  ↓
PlaybookエンジンがイベントをCallbackに送信
  ├── v2_playbook_on_start      (Playbook開始時)
  ├── v2_runner_on_ok           (タスク成功時)
  ├── v2_runner_on_failed       (タスク失敗時)
  ├── v2_runner_on_changed      (タスクで変更発生時)
  └── v2_playbook_on_stats      (統計情報・Playbook末尾)
  ↓
各Callback Pluginが受け取って処理（表示・保存・通知）

[defaults]
# ターミナル出力を見やすいYAML形式に変更
stdout_callback = yaml

# 追加のCallback Pluginを有効化（カンマ区切りで複数指定可）
callbacks_enabled = profile_tasks

Thursday 06 November 2026  11:30:00 +0900 (0:00:02.312)       0:00:05.401 ***
===============================================================================
install nginx ----------------------------------------------------- 2.31s
configure nginx template ------------------------------------------ 1.58s
start nginx service ----------------------------------------------- 0.80s
Gathering Facts --------------------------------------------------- 0.71s

# 実行結果をタイムスタンプ付きのJSONファイルに保存する例
ANSIBLE_STDOUT_CALLBACK=json ansible-playbook site.yml \
  > /var/log/ansible/$(date +%Y%m%d_%H%M%S).json 2>&1

# community.generalコレクションをインストール
ansible-galaxy collection install community.general

[defaults]
callbacks_enabled = community.general.slack

[callback_slack]
webhook_url = https://hooks.slack.com/services/TXXXXXXXX/BXXXXXXXX/XXXXXXXXXX
channel = #ansible-notify
username = AnsibleBot

# ARAとAPIサーバーをインストール
pip3 install ara[server]

# ARAがインストールしたCallback Pluginのパスを確認する
python3 -c "import ara; print(ara.__file__.replace('__init__.py', 'plugins/callback'))"
# 出力例（環境により異なります）
# /usr/local/lib/python3.11/site-packages/ara/plugins/callback

[defaults]
# ARAのCallback Pluginのパスを追加
callback_plugins = /usr/local/lib/python3.11/site-packages/ara/plugins/callback
callbacks_enabled = ara_default

# DBの初期化とAPIサーバーの起動
ara-manage migrate
ara-manage runserver 0.0.0.0:9191

# カスタムCallback Pluginの骨格
# ファイル: callback_plugins/my_custom.py

from ansible.plugins.callback import CallbackBase

class CallbackModule(CallbackBase):
    CALLBACK_VERSION = 2.0
    CALLBACK_TYPE = 'notification'
    CALLBACK_NAME = 'my_custom'
    CALLBACK_NEEDS_ENABLED = True

    def v2_runner_on_failed(self, result, ignore_errors=False):
        """タスク失敗時に呼ばれるメソッド"""
        host = result._host.get_name()
        task = result.task_name
        # ここに社内システムへの通知ロジックを書く
        pass

    def v2_playbook_on_stats(self, stats):
        """Playbook終了時に呼ばれるメソッド"""
        # ここに集計・レポート出力ロジックを書く
        pass

# 利用可能なCallback Pluginの一覧を確認する
ansible-doc -t callback -l
# 出力例（環境により異なります）
# ansible.posix.cgroup_perf_recap  Profiles tasks and hosts using cgroups
# community.general.slack          Sends play events to a Slack channel
# ara.plugins.callback.ara_default Records Ansible and AWX/Tower data

# ansible.cfgでfact cachingを有効化する例
[defaults]
fact_caching = jsonfile
fact_caching_connection = /tmp/ansible_facts
fact_caching_timeout = 86400

# 環境変数でAPIサーバーのURLを指定する
export ARA_API_SERVER=http://ara.internal:9191
ansible-playbook site.yml