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
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 }
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 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 env/settings - Settings for Runner itself):
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
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):
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.