Ansible Runner — ansible-runner 1.0.4 documentation

# 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.

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

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
  - Roles
  - Runner Artifacts Directory Hierarchy
  - Runner Artifact Job Events (Host and Playbook Events)
- Installing Ansible Runner
  - Using pip
  - Fedora
  - From source
  - Build the distribution
  - Building the base container image
  - Building the RPM
  - Changelog
- Using Runner as a standalone command line tool
  - Executing Runner in the foreground
  - Executing Runner in the background
  - Running Playbooks
  - Running Roles Directly
  - Outputting json (raw event data) to the console instead of normal output
- 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`
  - 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