ansible_runner package

Subpackages

• ansible_runner.callbacks package
  • Submodules
  • ansible_runner.callbacks.awx_display module
  • ansible_runner.callbacks.minimal module
  • Module contents
• ansible_runner.display_callback package
  • Submodules
  • ansible_runner.display_callback.cleanup module
  • ansible_runner.display_callback.display module
  • ansible_runner.display_callback.events module
  • ansible_runner.display_callback.minimal module
  • ansible_runner.display_callback.module module
  • Module contents

Submodules

ansible_runner.exceptions module

exception ansible_runner.exceptions.AnsibleRunnerException

Bases: exceptions.Exception

Generic Runner Error

exception ansible_runner.exceptions.CallbackError

Bases: ansible_runner.exceptions.AnsibleRunnerException

Exception occurred in Callback

exception ansible_runner.exceptions.ConfigurationError

Bases: ansible_runner.exceptions.AnsibleRunnerException

Misconfiguration of Runner

ansible_runner.interface module

ansible_runner.interface.init_runner(**kwargs)

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 ansible_runner.interface.run()

ansible_runner.interface.run(**kwargs)

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

Parameters:

• 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)

Returns:

A ansible_runner.runner.Runner object

ansible_runner.interface.run_async(**kwargs)

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 ansible_runner.interface.run()

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

ansible_runner.loader module

class ansible_runner.loader.ArtifactLoader(base_path)

Bases: object

Handles loading and caching file contents from disk

This class will load the file contents and attempt to deserialize the contents as either JSON or YAML. If the file contents cannot be deserialized, the contents will be returned to the caller as a string.

The deserialized file contents are stored as a cached object in the instance to avoid any additional reads from disk for subsequent calls to load the same file.

abspath(path)

Transform the path to an absolute path

Args:

path (string): The path to transform to an absolute path

Returns:

string: The absolute path to the file

get_contents(path)

Loads the contents of the file specified by path

Args:

path (string): The relative or absolute path to the file to

be loaded. If the path is relative, then it is combined with the base_path to generate a full path string

Returns:

string: The contents of the file as a string

Raises:

ConfigurationError: If the file cannot be loaded

isfile(path)

Check if the path is a file

Params path:The path to the file to check. If the path is relative it will be exanded to an absolute path Returns:boolean

load_file(path, objtype=None, encoding='utf-8')

Load the file specified by path

This method will first try to load the file contents from cache and if there is a cache miss, it will load the contents from disk

Args:

path (string): The full or relative path to the file to be loaded

encoding (string): The file contents text encoding

objtype (object): The object type of the file contents. This

is used to type check the deserialized content against the contents loaded from disk. Ignore serializing if objtype is string_types

Returns:

object: The deserialized file contents which could be either a

string object or a dict object

Raises:

ConfigurationError:

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)

Bases: object

event_callback(event_data)

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

events

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

Example:

{

“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_fact_cache(host)

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

classmethod handle_termination(pid, pidfile=None, is_cancel=True)

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

Parameters:

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

host_events(host)

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

run()

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

set_fact_cache(host, data)

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

stats

Returns the final high level stats from the Ansible run

Example:

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

status_callback(status)

stdout

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

ansible_runner.runner_config module

class ansible_runner.runner_config.ExecutionMode

ANSIBLE = 1

ANSIBLE_PLAYBOOK = 2

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)

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.

Example:

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

build_process_isolation_temp_dir()

Create a temporary directory for process isolation to use.

generate_ansible_command()

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

prepare()

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.

prepare_command()

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

prepare_env()

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

prepare_inventory()

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

wrap_args_with_cgexec(args)

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

wrap_args_with_process_isolation(args)

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)

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)

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.

update(**kwargs)

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

Bases: object

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

EVENT_DATA_RE = <_sre.SRE_Pattern object>

close()

flush()

write(data)

ansible_runner.utils.args2cmdline(*args)

ansible_runner.utils.check_isolation_executable_installed(isolation_executable)

Check that proot is installed.

ansible_runner.utils.cleanup_artifact_dir(path, num_keep=0)

ansible_runner.utils.collect_new_events(event_path, old_events)

Collect new events for the ‘events’ generator property

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

Write the artifact to disk at the specified path

Args:

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.

Returns:

string: The full path filename for the artifact that was generated

ansible_runner.utils.dump_artifacts(kwargs)

Introspect the kwargs and dump objects to disk

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

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

ansible_runner.utils.isinventory(obj)

Inspects the object and returns if it is an inventory

Args:

obj (object): The object to be inspected by this function

Returns:

boolean: True if the object is an inventory dict and False if it is not

ansible_runner.utils.isplaybook(obj)

Inspects the object and returns if it is a playbook

Args:

obj (object): The object to be inspected by this function

Returns:

boolean: True if the object is a list and False if it is not

ansible_runner.utils.open_fifo_write(path, data)

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