79 lines
2.9 KiB
ReStructuredText
79 lines
2.9 KiB
ReStructuredText
.. _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, there are currently two available
|
|
|
|
.. _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 }
|
|
|
|
.. _httpemitterplugin:
|
|
|
|
HTTP Status/Event Emitter Plugin
|
|
--------------------------------
|
|
|
|
This sends status and event data to a URL in the form of json encoded POST requests.
|
|
|
|
This plugin is available from the `ansible-runner-http github repo <https://github.com/ansible/ansible-runner-http>`_ and is also available to be installed from
|
|
pip::
|
|
|
|
$ pip install ansible-runner-http
|
|
|
|
In order to configure it, you can provide details in the Runner Settings file (see :ref:`runnersettings`):
|
|
|
|
* `runner_http_url`: The url to receive the ``POST``
|
|
* `runner_http_headers`: Headers to send along with the request.
|
|
|
|
The plugin also supports unix file-based sockets with:
|
|
|
|
* `runner_http_url`: The path to the unix socket
|
|
* `runner_http_path`: The path that will be included as part of the request to the socket
|
|
|
|
Some of these settings are also available as environment variables:
|
|
|
|
* RUNNER_HTTP_URL
|
|
* RUNNER_HTTP_PATH
|
|
|
|
.. _zmqemitterplugin:
|
|
|
|
ZeroMQ Status/Event Emitter Plugin
|
|
----------------------------------
|
|
|
|
TODO
|
|
|
|
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.
|