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.

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.