Go to Qiita Advent Calendar 2024 Top
LoginSignup
22
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

More than 3 years have passed since last update.

知名度の低い穴場中の穴場 Cisco Systems JapanAdvent Calendar 2019

Day 5
@oigarash

WebEx TeamsにPlaybookの結果を通知するAnsible Callback Plugin

Last updated at Posted at 2019-12-04

はじめに

この記事はシスコの有志による Cisco Systems Japan Advent Calendar 2019 の 2 日目として投稿しています。

2017年版: https://qiita.com/advent-calendar/2017/cisco
2018年版: https://qiita.com/advent-calendar/2018/cisco
2019年版: https://qiita.com/advent-calendar/2019/cisco

書くこともぱっと思いつかなかったので、去年に引き続き、Ansibleネタで。
結構長いAnsible Playbookを実行すると、終わるのを待ってられないので通知したくなるわけですが、普通だと、Playbookの最後に通知用のモジュールを使って送っていると思います。

しかしこの方法だと、Playbookを作る度にそれを実装したりしなければならなかったり、実行に失敗したときにも通知をできるようにしなきゃいけなかったりして結構面倒です。

まあ、Roleとか作って頑張ってもいいんですが、Callback Pluginを使って結構便利に実装できるのでCallback Pluginを使った方法を紹介したいと思います。

Callback Pluginの作成手順ですが公式になんとなくレベルで書いてあったかもしれないんですが、あまりちゃんとした記事もみあたらなかったので、Callback Pluginの作成手順などもあわせて説明してみました。

目標

以下のような機能をCallback Pluginで実装することが目標です。

  • Playbookの終了時に結果を通知できる
  • 全体のメッセージを変数で設定できる
  • ホストごとに、失敗したときと成功したときに設定できる

実行例

こんな感じになりました

サンプルのPlaybook

playbook_sample.yaml
---
- name: Sample Playbook to send WebEx message when Playbook complete
  gather_facts: no
  hosts: all
  connection: local
  vars:
    notify_webex_destination: foobar@example.com
    notify_webex_when_finished: The playbook completed
    notify_webex_when_success: "{{ inventory_hostname }} succeeded"
    notify_webex_when_failed: "{{ inventory_hostname }} failed"
  tasks:
    - name: Makes some hosts fail
      fail:
        msg: "{{ groups }}"
      when: inventory_hostname in groups.failure

以下の変数を設定することで動作を変更できます。

  • notify_webex_destination ... 通知の宛先
  • notify_webex_when_finished ... Playbookが終了した際に表示させるメッセージ
  • notify_webex_when_success ... ホストが成功したときに表示させるメッセージ
  • notify_webex_when_failed ... ホストが失敗したときに表示させるメッセージ

Callback Pluginの実装

Callback Pluginの作成手順

Callback Pluginの作成手順ですが、以下のような感じでPythonで書けます。
PythonファイルをAnsibleがPluginをロードするパスに置けばOKです(Playbook/Roleなら、callback_pluginsディレクトリ配下, 全体ならansible.cfgで設定したパス)。

親にCallbackBaseで、CallbackModuleというクラスを定義して、その中にトリガとなるイベントに対応するコールバック関数(v2_playbook_on_start)を定義します。

notify_webex.py
# Python2/3のコンパチやライブラリの衝突を防ぐために入れておく
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type

from ansible.plugins.callback import CallbackBase


class CallbackModule(CallbackBase):
    # Version。特に理由が無ければ 2.0
    CALLBACK_VERSION = 2.0
    # コンソール出力制御なら`stdout`。他は何でも良さげだが、notfication, agreegationが使われている
    CALLBACK_TYPE = 'notification'
    # Callback Pluginの名前
    CALLBACK_NAME = 'notify'
    # WhiteListで制御するかどうか
    CALLBACK_NEEDS_WHITELIST = True
    def __init__(self, *args, **kwargs):
        super(CallbackModule, self).__init__(*args, **kwargs)
        self.logged = []

    # 以下はトリガごとに実行する処理
    def v2_playbook_on_start(self, playbook):
        self.logged.append("Playbook {} started".format(playbook._file_name))

    def v2_playbook_on_task_start(self, task, is_conditional):
        self.logged.append("Task {}",format(self.task.name))

    def v2_playbook_on_stats(self, stats):
        self.loged.append(stats)
        with open('/tmp/log.txt', 'aw') as f:
            f.write(self.logged)

注意点としては、公式ドキュメントにコールバック関数がどのタイミングで実行されるのかがちゃんと書かれていないので、わかりにくいものに関してはトライアル&エラーが必要そうです。あと、v1, v2があるんですが今はv2が使われているみたいです。

具体的にどのようなコールバック関数を使えるのかはドキュメントを見てもなさそうだったので、Ansibleのコードをざっと眺めて使えそうなコールバック関数をまとめてみました。

注意: 2.7のコードを見てまとめたので変更があるかもしれません

  • v2_on_any ... 実装されている全てのタイミング
  • v2_runner_on_failed ... Taskが失敗したとき
  • v2_runner_on_ok ... TaskがOKのとき
  • v2_runner_on_skipped ... Taskがスキップされたとき
  • v2_runner_on_unreachable ... TaskでホストがUnreachableのとき
  • v2_runner_on_async_poll ... (未実装) Taskでasync pollを実行したとき
  • v2_runner_on_async_ok ... (未実装) TaskでAsync PollがOKのとき
  • v2_runner_on_async_failed ... (未実装) TaskでAsync Pollに失敗したとき
  • v2_playbook_on_start ... Playbook実行時
  • v2_playbook_on_notify ... PlayでNotify実行時
  • v2_playbook_on_no_hosts_matched ... Playbookのホストがマッチしないとき
  • v2_playbook_on_no_hosts_remaining ... max_fail_percentageを超えた場合に実行
  • v2_playbook_on_task_start ... PlayでTaskを開始するとき
  • v2_playbook_on_cleanup_task_start ... (未実装) PlaybookでCleanup Taskを実行するとき
  • v2_playbook_on_handler_task_start ... (未実装) PlaybookでHanderのTaskを実行するとき
  • v2_playbook_on_vars_prompt ... Playでvars_promptを実行するとき
  • v2_playbook_on_import_for_host ... (未実装)
  • v2_playbook_on_not_import_for_host ... (未実装)
  • v2_playbook_on_play_start ... Play開始時
  • v2_playbook_on_stats ... Playbookが終了したとき
  • v2_on_file_diff ... diffを結果として返すモジュールで実際に差分がある場合
  • v2_playbook_on_include ... include_の処理が発生したとき
  • v2_runner_item_on_ok ... Taskのループでの処理ごとにitemがOKのとき
  • v2_runner_item_on_failed ... Taskのループでの処理ごとにitemがfailedのとき
  • v2_runner_item_on_skipped ... Taskのループでの処理ごとにitemがskippedのとき
  • v2_runner_retry ... Task実行時
  • v2_runner_on_start ... Taskが開始されるとき(2.8から)

コールバック関数で変数を使う

コールバック関数によって渡される変数が異なります。例えばv2_playbook_on_startではPlaybookのオブジェクトが渡されますが、v2_playbook_on_statsでは、AggregateStatsオブジェクト(結果の情報が入る)が渡されます。

notify_webex.py
    # Playbookオブジェクトが渡される
    def v2_playbook_on_start(self, playbook):
        self.logged.append("Playbook {} started".format(playbook._file_name))

    # AggregateStatsオブジェクトが渡される
    def v2_playbook_on_stats(self, stats):
        self.loged.append(stats)
        with open('/tmp/log.txt', 'aw') as f:
            f.write(self.logged)

このため、渡してくれない情報を利用するにはひと工夫が必要です。

今回の例ではPlaybookで定義している変数を使いたかったので、まずv2_playbook_on_startでPlaybookのオブジェクトをselfに格納して、それをv2_playbook_on_statsで使っています。

更にPlaybook.get_plays()で、Playオブジェクトをとってきています。Playbookには複数のPlayを設定できるので、厳密には複数あった場合の処理も考えるべきなんでしょうが、ここでは面倒なので最後のPlayだけを対象にしています。

notify_webex.py
    def v2_playbook_on_start(self, playbook):
        self.playbook = playbook

    def v2_playbook_on_stats(self, stats):
        playbook = self.playbook
        play = playbook.get_plays()[-1]

ここからが更に面倒なんですが、Ansibleでは変数にJinja2テンプレートが使われている場合、そのまま変数を取ってこようとするとテンプレート化された値をコンバートしてくれません。

Ansible内部ではTemplarオブジェクトを使って変数内のテンプレートをコンバートすることができますが、Templarに利用する変数を渡す必要があります。これは別途VariableManagerで管理されているようです。

VariableManager.get_vars()で変数は取得可能ですが、この際に、対象となるPlayやHostを設定する必要があります。Taskも設定できますが今回はTaskの変数は使わないと思うので省略します。

あまり細々としたことを考えるのが面倒になってきたので、notify_webex_destination, notify_webex_when_finishedに関してはPlayで設定されている変数までを範囲にして取得し、notify_webex_when_successとnotify_webex_when_failedに関してはPlay+Hostに設定されている変数を対象としています。サンプルではinventory_hostnameをテンプレート変数として使っていますが、これはHostも設定しておかないとコンバートできないので、notify_webex_when_finishedとかで使うとエラーになってしまいます。

notify_webex.py
        variable_manager = play.get_variable_manager()
        inventory_hosts = variable_manager._inventory.get_hosts()
        play_vars = variable_manager.get_vars(play=play)

        templar = Templar(playbook._loader, variables=play_vars)
        destination = play_vars.get('notify_webex_destination')

        if destination is None:
            self._display.warning(
                "notify_webex_destination was not provided. Disalbed webexteam Callback plugin")
            return
        self.destination = templar.template(destination)

        messages = list()

        hosts = sorted(stats.processed.keys())
        for hostname in hosts:
            s = stats.summarize(hostname)
            host = [h for h in inventory_hosts if h.name == hostname][0]
            host_vars = variable_manager.get_vars(play=play, host=host)
            templar = Templar(playbook._loader, variables=host_vars)
            if s['failures'] > 0 or s['unreachable'] > 0:
                message_failed = host_vars.get('notify_webex_when_failed', None)
                if message_failed:
                    messages.append(templar.template(message_failed))
            else:
                message_success = host_vars.get(
                    'notify_webex_when_success', None)
                if message_success:
                    messages.append(templar.template(message_success))

        message_finished = play_vars.get('notify_webex_when_finished', None)
        messages.append(templar.template(message_finished))
        if messages:
            self.send_message("\n\n".join(messages))

WebExへの通知

なんかAnsibleの話で全然WebEx Teamsの話は出てきませんでしたね...
最後にWebEx Teamsに通知を送って終了です。
WebEx Teams APIに関しては結構ドキュメントがあると思うので割愛します...

    WEBEX_TOKEN = 'YOURTOKENHERE'
    WEBEX_API_URL = 'https://api.ciscospark.com/v1/'

    def send_message(self, message):
        headers = {
            "Authorization": "Bearer {}".format(self.WEBEX_TOKEN),
            "Content-Type": 'application/json'
        }
        payload = {
            'toPersonEmail': self.destination,
            'markdown': message
        }
        data = json.dumps(payload)
        try:
            response = open_url(self.WEBEX_API_URL + '/messages',
                                headers=headers, data=data, validate_certs=False)
            return response.read()
        except Exception as e:
            self._display.warning(u'Could not submit message to Webex Team: %s' %
                                  to_text(e))

最後に

このCallback Pluginのサンプルは以下にあります。

ちょっと手直しすればSxxckとかMxxxxsxxt Teamsとかでも自由に使えると思います。

22
1
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
22
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?