Ansible Runner

Ansible Runner is a tool and Python library designed to provide a stable, consistent interface abstraction for Ansible. It is used to interface with ansible and ansible-playbook tasks, making it easier to embed Ansible into other systems like CI/CD platforms (e.g., Jenkins) or automated tooling without managing the complexities of the Ansible interface directly.

It modularizes the task execution and output gathering logic (similar to how Ansible AWX operates) and provides a system for storing stdout, host-level event data, and fact data.

Plugins receive two distinct types of events from ansible-runner:

1. status events: Emitted whenever the Runner's status changes (e.g., moving to running). Example: {"status": "running", "runner_ident": "XXXX" }

2. ansible events: Emitted during playbook execution for every event received from Ansible (e.g., host or playbook events). Example: {"runner_ident": "XXXX", <rest of event structure> }

Ansible Runner provides several command modes to control how the process is launched:

• run: Starts Runner in the foreground. It waits for the underlying Ansible process to complete before returning. Output is visible in the console and saved to the artifacts directory.
• start: Starts Runner as a background daemon process and generates a pid file.
• stop: Terminates a background process previously started with start.
• is-alive: Checks the status of a background process started with start.

Regardless of the mode, Runner creates an artifacts directory containing the output and status. You can control the location of the artifacts directory using the -i IDENT argument; otherwise, a random UUID is used.

ansible-runner run /tmp/private -p playbook.yml

Ansible Runner can be driven by a directory structure that maps inputs to specific locations. This allows automation tools to gather inputs from various sources (like databases) and prepare them in a single directory for Runner to consume.

An active configuration follows this hierarchy:

.
├── env
│   ├── envvars
│   ├── extravars
│   ├── passwords
│   ├── cmdline
│   ├── settings
│   └── ssh_key
├── inventory
│   └── hosts
└── project
    ├── test.yml
    └── roles
        └── testrole
            ├── defaults
            ├── handlers
            ├── meta
            ├── tasks
            └── vars

Note that not all files are required; Runner will use defaults or omit values if they are not provided.

In the context of Ansible Runner, an Execution Environment is the container runtime execution of Ansible using an OCI-compliant container image. This image bundles Ansible Base, Ansible Collection Content, and necessary runtime dependencies.

When using Execution Environments, Ansible Runner provides process isolation via a container runtime (using podman by default). This allows you to run Ansible jobs in a consistent, reproducible, and portable manner, similar to how they run in Ansible AWX.

Every Ansible Runner job has a unique identifier (which is also the name of the artifacts subfolder). When a container is launched for job isolation, it is named using the pattern:

ansible_runner_<job identifier>

Some characters from the job identifier may be replaced with underscores to ensure compatibility with the naming constraints of Podman and Docker. This name is used internally to manage the container, such as stopping it if a job is canceled.

You can interact with Ansible Runner in three primary ways depending on your use case:

1. Standalone Command Line Tool: Use the ansible-runner CLI to run tasks in the foreground or asynchronously in the background.
2. Python Module: Import ansible-runner as a library to integrate Ansible execution directly into your Python applications.
3. Plugin Interface: Configure Runner to send status and event data to external systems (e.g., sending status to Ansible AWX or events to an external logging service).

Ansible Runner supports executing jobs on a remote host via a three-phase process. This is primarily designed for use with Receptor.

1. Transmit: Converts the job (private data directory and parameters) into a compressed binary stream emitted to stdout. This stage uses the same command-line parameters as the run command.
2. Worker: Accepts the binary stream, executes the job, and generates a new compressed binary stream containing job events and artifacts. It can optionally use --private-data-dir to extract the transmitted contents into a specific directory.
3. Process: Accepts the result stream from the worker, processes job events, fires callbacks, and saves artifacts to the specified data directory.

ansible-runner transmit ./demo -p test.yml | ansible-runner worker | ansible-runner process ./demo