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 -p playbook.yml run /tmp/private

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 starts ansible-runner in the foreground and waits until the underlying Ansible process completes before returning
  • start starts ansible-runner as a background daemon process and generates a pid file
  • stop terminates an ansible-runner process that was launched in the background with start
  • is-alive checks the status of an ansible-runner process that was started in the background with start
  • adhoc will run ad-hoc ansible commands inside a containerized Ansible Execution Environment
  • playbook will run ansible-playbook commands inside a containerized Ansible Execution Environment

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 --playbook test.yml run demo

Running Modules Directly

An example invocating the debug module with demo as a private directory:

$ ansible-runner -m debug --hosts localhost -a msg=hello run demo

Running Roles Directly

An example invocation using demo as private directory and localhost as target:

$ ansible-runner --role testrole --hosts localhost run demo

Ansible roles directory can be provided with --roles-path option. Role variables can be passed with --role-vars at runtime.

Running Ansible adhoc Commands with Execution Environments

An example invocation using the ping module and localhost as target:

$ ansible-runner adhoc localhost -m ping

Something to note here is that implicit localhost in this context is a containerized instantiation of an Ansible Execution Environment and as such you will not get Ansible Facts about your system if using the setup module.

For more information, see Using Runner with Execution Environmnets

Running Ansible ansible-playbook Commands with Execution Environments

An example invocation using the demo.yml playbook and inventory.ini inventory file:

$ ansible-runner playbook demo.yml -i inventory.ini

Something to note here is that implicit localhost in this context is a containerized instantiation of an Ansible Execution Environment and as such you will not get Ansible Facts about your system if using gather_facts: true and targeting localhost in your playbook without explicit host definition in your inventory.

For more information, see Using Runner with Execution Environmnets

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.

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