1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
|
.. _externalintf:
Sending Runner Status and Events to External Systems
====================================================
**Runner** can store event and status data locally for retrieval, it can also emit this information via callbacks provided to the module interface.
Alternatively **Runner** can be configured to send events to an external system via installable plugins. Currently, there are two example plugins are available.
* HTTP Status/Event Emitter Plugin - `ansible-runner-http GitHub repo <https://github.com/ansible/ansible-runner-http>`_
* ZeroMQ Status/Event Emitter Plugin - `ansible-runner-zeromq GitHub repo <https://github.com/ansible/ansible-runner-zeromq>`_
Please refer to respective repos to configure these plugins.
.. _plugineventstructure:
Event Structure
---------------
There are two types of events that are emitted via plugins:
* status events:
These are sent whenever Runner's status changes (see :ref:`runnerstatushandler`) for example::
{"status": "running", "runner_ident": "XXXX" }
* ansible events:
These are sent during playbook execution for every event received from **Ansible** (see :ref:`Playbook and Host Events<artifactevents>`) for example::
{"runner_ident": "XXXX", <rest of event structure> }
Writing your own Plugin
-----------------------
In order to write your own plugin interface and have it be picked up and used by **Runner** there are a few things that you'll need to do.
* Declare the module as a Runner entrypoint in your setup file
(`ansible-runner-http has a good example of this <https://github.com/ansible/ansible-runner-http/blob/master/setup.py>`_)::
entry_points=('ansible_runner.plugins': 'modname = your_python_package_name'),
* Implement the ``status_handler()`` and ``event_handler()`` functions at the top of your package, for example see
`ansible-runner-http events.py <https://github.com/ansible/ansible-runner-http/blob/master/ansible_runner_http/events.py>`_ and the ``__init__``
import `at the top of the module package <https://github.com/ansible/ansible-runner-http/blob/master/ansible_runner_http/__init__.py>`_
After installing this, **Runner** will see the plugin and invoke the functions when status and events are sent. If there are any errors in your plugin
they will be raised immediately and **Runner** will fail.
|
