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
ZeroMQ Status/Event Emitter Plugin - ansible-runner-zeromq GitHub repo
Please refer to respective repos to configure these plugins.
Event Structure
There are two types of events that are emitted via plugins:
status events:
These are sent whenever Runner’s status changes (see Runner.status_handler) for example:
{"status": "running", "runner_ident": "XXXX" }
ansible events:
These are sent during playbook execution for every event received from Ansible (see Playbook and Host Events) 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):
entry_points=('ansible_runner.plugins': 'modname = your_python_package_name'),
Implement the
status_handler()
andevent_handler()
functions at the top of your package, for example see ansible-runner-http events.py and the__init__
import at the top of the module package
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.