ansible_runner package


ansible_runner.exceptions module

exception ansible_runner.exceptions.AnsibleRunnerException[source]

Bases: exceptions.Exception

Generic Runner Error

exception ansible_runner.exceptions.CallbackError[source]

Bases: ansible_runner.exceptions.AnsibleRunnerException

Exception occurred in Callback

exception ansible_runner.exceptions.ConfigurationError[source]

Bases: ansible_runner.exceptions.AnsibleRunnerException

Misconfiguration of Runner

ansible_runner.interface module


Initialize the Runner() instance

This function will properly initialize both run() and run_async() functions in the same way and return a value instance of Runner.

See parameters given to**kwargs)[source]

Run an Ansible Runner task in the foreground and return a Runner object when complete.

  • private_data_dir (str) – The directory containing all runner metadata needed to invoke the runner module. Output artifacts will also be stored here for later consumption.
  • ident (str) – The run identifier for this invocation of Runner. Will be used to create and name the artifact directory holding the results of the invocation.
  • json_mode (bool) – Store event data in place of stdout on the console and in the stdout file
  • playbook (str or filename or list) – The playbook (either supplied here as a list or string… or as a path relative to private_data_dir/project) that will be invoked by runner when executing Ansible.
  • module – The module that will be invoked in ad-hoc mode by runner when executing Ansible.
  • module_args – The module arguments that will be supplied to ad-hoc mode.
  • host_pattern – The host pattern to match when running in ad-hoc mode.
  • inventory (str or dict or list) –
    Overridees the inventory directory/file (supplied at private_data_dir/inventory) with
    a specific host or list of hosts. This can take the form of
    • Path to the inventory file in the private_data_dir
    • Native python dict supporting the YAML/json inventory structure
    • A text INI formatted string
    • A list of inventory sources, or an empty list to disable passing inventory
  • roles_path – Directory or list of directories to assign to ANSIBLE_ROLES_PATH
  • envvars (dict) – Environment variables to be used when running Ansible. Environment variables will also be read from env/envvars in private_data_dir
  • extravars (dict) – Extra variables to be passed to Ansible at runtime using -e. Extra vars will also be read from env/extravars in private_data_dir.
  • passwords (dict) – A dictionary containing password prompt patterns and response values used when processing output from Ansible. Passwords will also be read from env/passwords in private_data_dir.
  • settings (dict) – A dictionary containing settings values for the ansible-runner runtime environment. These will also be read from env/settings in private_data_dir.
  • ssh_key (str) – The ssh private key passed to ssh-agent as part of the ansible-playbook run.
  • cmdline (str) – Command line options passed to Ansible read from env/cmdline in private_data_dir
  • limit (str) – Matches ansible’s --limit parameter to further constrain the inventory to be used
  • forks (int) – Control Ansible parallel concurrency
  • verbosity (int) – Control how verbose the output of ansible-playbook is
  • quiet (bool) – Disable all output
  • artifact_dir (str) – The path to the directory where artifacts should live, this defaults to ‘artifacts’ under the private data dir
  • project_dir (str) – The path to the playbook content, this defaults to ‘project’ within the private data dir
  • rotate_artifacts (int) – Keep at most n artifact directories, disable with a value of 0 which is the default
  • event_handler (function) – An optional callback that will be invoked any time an event is received by Runner itself
  • cancel_callback (function) – An optional callback that can inform runner to cancel (returning True) or not (returning False)
  • finished_callback (function) – An optional callback that will be invoked at shutdown after process cleanup.
  • status_handler (function) – An optional callback that will be invoked any time the status changes (e.g…started, running, failed, successful, timeout)
  • process_isolation (bool) – Enable limiting what directories on the filesystem the playbook run has access to.
  • process_isolation_executable (str) – Path to the executable that will be used to provide filesystem isolation (default: bwrap)
  • process_isolation_path (str) – Path that an isolated playbook run will use for staging. (default: /tmp)
  • process_isolation_hide_paths (str or list) – A path or list of paths on the system that should be hidden from the playbook run.
  • process_isolation_show_paths (str or list) – A path or list of paths on the system that should be exposed to the playbook run.
  • process_isolation_ro_paths (str or list) – A path or list of paths on the system that should be exposed to the playbook run as read-only.
  • resource_profiling (bool) – Enable collection of resource utilization data during playbook execution.
  • resource_profiling_base_cgroup (str) – Name of existing cgroup which will be sub-grouped in order to measure resource utilization (default: ansible-runner)
  • resource_profiling_cpu_poll_interval (float) – Interval (in seconds) between CPU polling for determining CPU usage (default: 0.25)
  • resource_profiling_memory_poll_interval (float) – Interval (in seconds) between memory polling for determining memory usage (default: 0.25)
  • resource_profiling_pid_poll_interval (float) – Interval (in seconds) between polling PID count for determining number of processes used (default: 0.25)
  • resource_profiling_results_dir (str) – Directory where profiling data files should be saved (defaults to profiling_data folder inside private data dir)
  • directory_isolation_base_path (str) – An optional path will be used as the base path to create a temp directory, the project contents will be copied to this location which will then be used as the working directory during playbook execution.
  • fact_cache (str) – A string that will be used as the name for the subdirectory of the fact cache in artifacts directory. This is only used for ‘jsonfile’ type fact caches.
  • fact_cache_type (str) – A string of the type of fact cache to use. Defaults to ‘jsonfile’.
  • omit_event_data (bool) – Omits extra ansible event data from event payload (stdout and event still included)
  • only_failed_event_data (bool) – Omits extra ansible event data unless it’s a failed event (stdout and event still included)

A ansible_runner.runner.Runner object


Runs an Ansible Runner task in the background which will start immediately. Returns the thread object and a Runner object.

This uses the same parameters as

Returns:A tuple containing a threading.Thread object and a ansible_runner.runner.Runner object

ansible_runner.runner module

class ansible_runner.runner.Runner(config, cancel_callback=None, remove_partials=True, event_handler=None, finished_callback=None, status_handler=None)[source]

Bases: object


Invoked for every Ansible event to collect stdout with the event data and store it for later use


A generator that will return all ansible job events in the order that they were emitted from Ansible



“event”:”runner_on_ok”, “uuid”:”00a50d9c-161a-4b74-b978-9f60becaf209”, “stdout”:”ok: [localhost] => {rn ” msg”:”Test!”rn}”, “counter”:6, “pid”:740, “created”:”2018-04-05T18:24:36.096725”, “end_line”:10, “start_line”:7, “event_data”:{

“play_pattern”:”all”, “play”:”all”, “task”:”debug”, “task_args”:”msg=Test!”, “remote_addr”:”localhost”, “res”:{

“msg”:”Test!”, “changed”:false, “_ansible_verbose_always”:true, “_ansible_no_log”:false

}, “pid”:740, “play_uuid”:”0242ac11-0002-443b-cdb1-000000000006”, “task_uuid”:”0242ac11-0002-443b-cdb1-000000000008”, “event_loop”:null, “playbook_uuid”:”634edeee-3228-4c17-a1b4-f010fdd42eb2”, “playbook”:”test.yml”, “task_action”:”debug”, “host”:”localhost”, “task_path”:”/tmp/demo/project/test.yml:3”




Get the entire fact cache only if the fact_cache_type is ‘jsonfile’

classmethod handle_termination(pid, pidfile=None, is_cancel=True)[source]

Internal method to terminate a subprocess spawned by pexpect representing an invocation of runner.

  • pid – the process id of the running the job.
  • pidfile – the daemon’s PID file
  • is_cancel – flag showing whether this termination is caused by instance’s cancel_flag.

Given a host name, this will return all task events executed on that host


Launch the Ansible task configured in self.config (A RunnerConfig object), returns once the invocation is complete

set_fact_cache(host, data)[source]

Set the entire fact cache data only if the fact_cache_type is ‘jsonfile’


Returns the final high level stats from the Ansible run

{‘dark’: {}, ‘failures’: {}, ‘skipped’: {}, ‘ok’: {u’localhost’: 2}, ‘processed’: {u’localhost’: 1}}

Returns an open file handle to the stdout representing the Ansible run

ansible_runner.runner_config module

class ansible_runner.runner_config.ExecutionMode[source]
NONE = 0
RAW = 3
class ansible_runner.runner_config.RunnerConfig(private_data_dir=None, playbook=None, ident=UUID('f77854b0-587a-4e24-a868-286c788de812'), inventory=None, roles_path=None, limit=None, module=None, module_args=None, verbosity=None, quiet=False, json_mode=False, artifact_dir=None, rotate_artifacts=0, host_pattern=None, binary=None, extravars=None, suppress_ansible_output=False, process_isolation=False, process_isolation_executable=None, process_isolation_path=None, process_isolation_hide_paths=None, process_isolation_show_paths=None, process_isolation_ro_paths=None, resource_profiling=False, resource_profiling_base_cgroup='ansible-runner', resource_profiling_cpu_poll_interval=0.25, resource_profiling_memory_poll_interval=0.25, resource_profiling_pid_poll_interval=0.25, resource_profiling_results_dir=None, tags=None, skip_tags=None, fact_cache_type='jsonfile', fact_cache=None, ssh_key=None, project_dir=None, directory_isolation_base_path=None, envvars=None, forks=None, cmdline=None, omit_event_data=False, only_failed_event_data=False)[source]

Bases: object

A Runner configuration object that’s meant to encapsulate the configuration used by the ansible_runner.runner.Runner object to launch and manage the invocation of ansible and ansible-playbook

Typically this object is initialized for you when using the standard run interfaces in ansible_runner.interface but can be used to construct the Runner configuration to be invoked elsewhere. It can also be overridden to provide different functionality to the Runner object.

>>> rc = RunnerConfig(...)
>>> r = Runner(config=rc)

Create a temporary directory for process isolation to use.


Given that the RunnerConfig preparation methods have been run to gather the inputs this method will generate the ansible or ansible-playbook command that will be used by the ansible_runner.runner.Runner object to start the process


Performs basic checks and then properly invokes

  • prepare_inventory
  • prepare_env
  • prepare_command

It’s also responsible for wrapping the command with the proper ssh agent invocation and setting early ANSIBLE_ environment variables.


Determines if the literal ansible or ansible-playbook commands are given and if not calls ansible_runner.runner_config.RunnerConfig.generate_ansible_command()


Manages reading environment metadata files under private_data_dir and merging/updating with existing values so the ansible_runner.runner.Runner object can read and use them easily


Prepares the inventory default under private_data_dir if it’s not overridden by the constructor.


Wrap existing command line with cgexec in order to profile resource usage

Wrap existing command line with bwrap to restrict access to:
  • self.process_isolation_path (generally, /tmp) (except for own /tmp files)
wrap_args_with_ssh_agent(args, ssh_key_path, ssh_auth_sock=None, silence_ssh_add=False)[source]

Given an existing command line and parameterization this will return the same command line wrapped with the necessary calls to ssh-agent

ansible_runner.utils module

class ansible_runner.utils.Bunch(**kwargs)[source]

Bases: object

Collect a bunch of variables together in an object. This is a slight modification of Alex Martelli’s and Doug Hudgeon’s Bunch pattern.

class ansible_runner.utils.OutputEventFilter(handle, event_callback, suppress_ansible_output=False, output_json=False)[source]

Bases: object

File-like object that looks for encoded job events in stdout data.

EVENT_DATA_RE = <_sre.SRE_Pattern object>

Check that proot is installed.

ansible_runner.utils.cleanup_artifact_dir(path, num_keep=0)[source]
ansible_runner.utils.collect_new_events(event_path, old_events)[source]

Collect new events for the ‘events’ generator property

ansible_runner.utils.dump_artifact(obj, path, filename=None)[source]

Write the artifact to disk at the specified path

obj (string): The string object to be dumped to disk in the specified
path. The artifact filename will be automatically created

path (string): The full path to the artifacts data directory.

filename (string, optional): The name of file to write the artifact to.
If the filename is not provided, then one will be generated.
string: The full path filename for the artifact that was generated

Introspect the kwargs and dump objects to disk

ansible_runner.utils.ensure_str(s, encoding='utf-8', errors='strict')[source]

Copied from six==1.12

Coerce s to str. For Python 2:

  • unicode -> encoded to str
  • str -> str
For Python 3:
  • str -> str
  • bytes -> decoded to str

Inspects the object and returns if it is an inventory

obj (object): The object to be inspected by this function
boolean: True if the object is an inventory dict and False if it is not

Inspects the object and returns if it is a playbook

obj (object): The object to be inspected by this function
boolean: True if the object is a list and False if it is not
ansible_runner.utils.open_fifo_write(path, data)[source]

open_fifo_write opens the fifo named pipe in a new thread. This blocks the thread until an external process (such as ssh-agent) reads data from the pipe.

Module contents