Ansible Runner

Ansible Runner is a tool and python library that helps when interfacing with Ansible directly or as part of another system whether that be through a container image interface, as a standalone tool, or as a Python module that can be imported. The goal is to provide a stable and consistent interface abstraction to Ansible. This allows Ansible to be embedded into other systems that don’t want to manage the complexities of the interface on their own (such as CI/CD platforms, Jenkins, or other automated tooling).

Ansible Runner represents the modularization of the part of Ansible Tower/AWX that is responsible for running ansible and ansible-playbook tasks and gathers the output from it. It does this by presenting a common interface that doesn’t change, even as Ansible itself grows and evolves.

Part of what makes this tooling useful is that it can gather its inputs in a flexible way (See Introduction to Ansible Runner:). It also has a system for storing the output (stdout) and artifacts (host-level event data, fact data, etc) of the playbook run.

There are 3 primary ways of interacting with Runner

• A standalone command line tool (ansible-runner) that can be started in the foreground or run in the background asynchronously
• A reference container image that can be used as a base for your own images and will work as a standalone container or running in Openshift or Kubernetes
• A python module - library interface

Ansible Runner can also be configured to send status and event data to other systems using a plugin interface, see Sending Runner Status and Events to External Systems.

Examples of this could include:

• Sending status to Ansible Tower/AWX
• Sending events to an external logging service

Contents:

• Introduction to Ansible Runner
  • Runner Input Directory Hierarchy
  • The env directory
  • env/envvars
  • env/extravars
  • env/passwords
  • env/cmdline
  • env/ssh_key
  • env/settings - Settings for Runner itself
  • Inventory
  • Project
  • Modules
  • Roles
  • Runner Artifacts Directory Hierarchy
  • Runner Artifact Job Events (Host and Playbook Events)
  • Runner Profiling Data Directory
• Installing Ansible Runner
  • Using pip
  • Fedora
  • Debian
  • From source
  • Build the distribution
  • Building the base container image
  • Building the RPM
  • Changelog
• Sending Runner Status and Events to External Systems
  • Event Structure
  • HTTP Status/Event Emitter Plugin
  • ZeroMQ Status/Event Emitter Plugin
  • Writing your own Plugin
• Using Runner as a standalone command line tool
  • Executing Runner in the foreground
  • Executing Runner in the background
  • Running Playbooks
  • Running Modules Directly
  • Running Roles Directly
  • Running with Process Isolation
  • Running with Directory Isolation
  • Outputting json (raw event data) to the console instead of normal output
  • Cleaning up artifact directories
• Using Runner as a Python Module Interface to Ansible
  • Helper Interfaces
  • run() helper function
  • run_async() helper function
  • The Runner object
  • Runner.stdout
  • Runner.events
  • Runner.stats
  • Runner.host_events
  • Runner.get_fact_cache
  • Runner.event_handler
  • Runner.cancel_callback
  • Runner.finished_callback
  • Runner.status_handler
  • Usage examples
  • Providing custom behavior and inputs
• Using Runner as a container interface to Ansible
  • Overriding the reference container image
  • Gathering output from the reference container image
  • Changing the console output to emit raw events

Indices and tables

• Index
• Module Index
• Search Page