Using Runner as a standalone command line tool
The Ansible Runner command line tool can be used as a standard command line interface to Ansible itself but is primarily intended to fit into automation and pipeline workflows. Because of this, it has a bit of a different workflow than Ansible itself because you can select between a few different modes to launch the command.
While you can launch Runner and provide it all of the inputs as arguments to the command line (as you do with Ansible itself),
there is another interface where inputs are gathered into a single location referred to in the command line parameters as private_data_dir
.
(see Runner Input Directory Hierarchy)
To view the parameters accepted by ansible-runner
:
$ ansible-runner --help
An example invocation of the standalone ansible-runner
utility:
$ ansible-runner run /tmp/private -p playbook.yml
Where playbook.yml is the playbook from the /tmp/private/projects
directory, and run
is the command mode you want to invoke Runner with
The different commands that runner accepts are:
run
startsansible-runner
in the foreground and waits until the underlying Ansible process completes before returningstart
startsansible-runner
as a background daemon process and generates a pid filestop
terminates anansible-runner
process that was launched in the background withstart
is-alive
checks the status of anansible-runner
process that was started in the background withstart
While Runner is running it creates an artifacts
directory (see Runner Artifacts Directory Hierarchy) regardless of what mode it was started
in. The resulting output and status from Ansible will be located here. You can control the exact location underneath the artifacts
directory
with the -i IDENT
argument to ansible-runner
, otherwise a random UUID will be generated.
Executing Runner in the foreground
When launching Runner with the run
command, as above, the program will stay in the foreground and you’ll see output just as you expect from a normal
Ansible process. Runner will still populate the artifacts
directory, as mentioned in the previous section, to preserve the output and allow processing
of the artifacts after exit.
Executing Runner in the background
When launching Runner with the start
command, the program will generate a pid file and move to the background. You can check its status with the
is-alive
command, or terminate it with the stop
command. You can find the stdout, status, and return code in the artifacts
directory.
Running Playbooks
An example invocation using demo
as private directory:
$ ansible-runner run demo --playbook test.yml
Running Modules Directly
An example invocating the debug
module with demo
as a private directory:
$ ansible-runner run demo -m debug --hosts localhost -a msg=hello
Running Roles Directly
An example invocation using demo
as private directory and localhost
as target:
$ ansible-runner run demo --role testrole --hosts localhost
Ansible roles directory can be provided with --roles-path
option. Role variables can be passed with --role-vars
at runtime.
Running with Process Isolation
Runner supports process isolation. Process isolation creates a new mount namespace where the root is on a tmpfs that is invisible from the host
and is automatically cleaned up when the last process exits. You can enable process isolation by providing the --process-isolation
argument on
the command line. Runner as of version 2.0 defaults to using podman
as the process isolation executable, but supports
using any executable that is compatible with the bubblewrap
CLI arguments by passing in the --process-isolation-executable
argument:
$ ansible-runner --process-isolation ...
Runner supports various process isolation arguments that allow you to provide configuration details to the process isolation executable. To view the complete
list of arguments accepted by ansible-runner
:
$ ansible-runner --help
Running with Directory Isolation
If you need to be able to execute multiple tasks in parallel that might conflict with each other or if you want to make sure a single invocation of Ansible/Runner doesn’t pollute or overwrite the playbook content you can give a base path:
$ ansible-runner --directory-isolation-base-path /tmp/runner
Runner will copy the project directory to a temporary directory created under that path, set it as the working directory, and execute from that location. After running that temp directory will be cleaned up and removed.
Specifying an Alternate Inventory
The default inventory, if not specified, will be <private_data_dir>/inventory/
.
All files within this subdirectory of the private data directory will be processed as
potential inventory host files. You may specify a different inventory using the --inventory
option. This value may be one of:
A file name located within
<private_data_dir>/inventory/
.An absolute or relative path to an alternate inventory file or directory. This path is not required to be inside of the private data directory.
Examples:
# Use inventory <private_data_dir>/inventory/hosts.backup
$ ansible-runner run demo -p test.yml --inventory hosts.backup
# Use inventory in the /path/to/alternate-inventory directory (outside of <private_data_dir>)
$ ansible-runner run demo -p test.yml --inventory /path/to/alternate-inventory
# Use inventory in the inventory2 subdirectory, relative to current directory
$ ansible-runner run demo -p test.yml --inventory inventory2
Note
This option has no effect when using process isolation.
Outputting json (raw event data) to the console instead of normal output
Runner supports outputting json event data structure directly to the console (and stdout file) instead of the standard Ansible output, thus
mimicking the behavior of the json
output plugin. This is in addition to the event data that’s already present in the artifact directory. All that is needed
is to supply the -j
argument on the command line:
$ ansible-runner ... -j ...
Cleaning up artifact directories
Using the command line argument --rotate-artifacts
allows you to control the number of artifact directories that are present. Given a number as the parameter
for this argument will cause Runner to clean up old artifact directories. The default value of 0
disables artifact directory cleanup.