ansible_runner package¶
Submodules¶
ansible_runner.exceptions module¶
-
exception
ansible_runner.exceptions.
AnsibleRunnerException
[source]¶ Bases:
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¶
-
ansible_runner.interface.
init_runner
(**kwargs)[source]¶ 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)[source]¶ 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
- Overridees the inventory directory/file (supplied at
- 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
inprivate_data_dir
- extravars (dict) – Extra variables to be passed to Ansible at runtime using
-e
. Extra vars will also be read fromenv/extravars
inprivate_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
inprivate_data_dir
. - settings (dict) – A dictionary containing settings values for the
ansible-runner
runtime environment. These will also be read fromenv/settings
inprivate_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
inprivate_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)[source]¶ 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 aansible_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
-
event_callback
(event_data)[source]¶ 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”
}
}
-
classmethod
handle_termination
(pid, pidfile=None, is_cancel=True)[source]¶ 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)[source]¶ Given a host name, this will return all task events executed on that host
-
run
()[source]¶ 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’
-
stats
¶ Returns the final high level stats from the Ansible run
- Example:
- {‘dark’: {}, ‘failures’: {}, ‘skipped’: {}, ‘ok’: {u’localhost’: 2}, ‘processed’: {u’localhost’: 1}}
-
stdout
¶ Returns an open file handle to the stdout representing the Ansible run
-
ansible_runner.runner_config module¶
-
class
ansible_runner.runner_config.
ExecutionMode
[source]¶ Bases:
object
-
ANSIBLE
= 1¶
-
ANSIBLE_PLAYBOOK
= 2¶
-
NONE
= 0¶
-
RAW
= 3¶
-
-
class
ansible_runner.runner_config.
RunnerConfig
(private_data_dir=None, playbook=None, ident=UUID('d1035c9c-861e-4df9-b50f-b50ed34bf80d'), 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 theansible_runner.runner.Runner
object to launch and manage the invocation ofansible
andansible-playbook
Typically this object is initialized for you when using the standard
run
interfaces inansible_runner.interface
but can be used to construct theRunner
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
()[source]¶ Create a temporary directory for process isolation to use.
-
generate_ansible_command
()[source]¶ Given that the
RunnerConfig
preparation methods have been run to gather the inputs this method will generate theansible
oransible-playbook
command that will be used by theansible_runner.runner.Runner
object to start the process
-
prepare
()[source]¶ 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
()[source]¶ Determines if the literal
ansible
oransible-playbook
commands are given and if not callsansible_runner.runner_config.RunnerConfig.generate_ansible_command()
-
prepare_env
()[source]¶ Manages reading environment metadata files under
private_data_dir
and merging/updating with existing values so theansible_runner.runner.Runner
object can read and use them easily
-
prepare_inventory
()[source]¶ Prepares the inventory default under
private_data_dir
if it’s not overridden by the constructor.
-
wrap_args_with_cgexec
(args)[source]¶ Wrap existing command line with cgexec in order to profile resource usage
-
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
= re.compile('\\x1b\\[K((?:[A-Za-z0-9+/=]+\\x1b\\[\\d+D)+)\\x1b\\[K')¶
-
-
ansible_runner.utils.
check_isolation_executable_installed
(isolation_executable)[source]¶ Check that proot is installed.
-
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
- 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.
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
-
ansible_runner.utils.
isinventory
(obj)[source]¶ 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