Using Runner with Execution Environments

Execution Environments are meant to be a consistent, reproducible, portable, and sharable method to run Ansible Automation jobs in the exact same way on your laptop as they are executed in Ansible AWX. This aids in the development of automation jobs and Ansible Content that is meant to be run in Ansible AWX, Ansible Tower, or via Red Hat Ansible Automation Platform in a predictable way.

More specifically, the term Execution Environments within the context of Ansible Runner refers to the container runtime execution of Ansible via Ansible Runner within an OCI Compliant Container Runtime using an OCI Compliant Container Image that appropriately bundles Ansible Base, Ansible Collection Content, and the runtime dependencies required to support these contents. The base image is the Red Hat Enterprise Linux Universal Base Image and the build tooling provided by Ansible Builder aids in the creation of these images.

All aspects of running Ansible Runner in standalone mode (see: Using Runner as a standalone command line tool) are true here with the exception that the process isolation is inherently a container runtime (podman by default).

Using Execution Environments from Protected Registries

When a job is run that uses an execution environment container image from a private/protected registry, you will first need to authenticate to the registry.

If you are running the job manually via ansible-runner run, logging in on the command line via podman login first is a method of authentication. Alternatively, creating a container_auth_data dictionary with the keys host, username, and password and putting that in the job’s env/settings file is another way to ensure a successful pull of a protected execution environment container image. Note that this involves listing sensitive information in a file which will not automatically get cleaned up after the job run is complete.

When running a job remotely via AWX or Ansible Tower, Ansible Runner can pick up the authentication information from the Container Registry Credential that was provided by the user. The host, username, password, and verify_ssl inputs from the credential are passed into Ansible Runner via the container_auth_data dictionary as key word arguments into a json file which gets deleted at the end of the job run (even if the job was canceled/interrupted), enabling the bypassing of sensitive information from any potentially persistent job-related files.

Emulating the Ansible CLI

As previously mentioned, a primary goal of adding the Execution Environment CLI interface is to aid in the creation of Ansible Automation jobs and content. The approach here is to make it as similar as possible to the way Ansible users are accustomed to using Ansible today. There are two subcommands, adhoc and playbook that have been added to accommodate this. The adhoc subcommand to ansible-runner is synonymous with ansible and the playbook subcommand to ansible-runner is synonymous with ansible-playbook. Examples are below.

Running Ansible adhoc

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.

Running Ansible playbook

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.

Notes and Considerations

There are some differences between using Ansible Runner and running Ansible directly from the command line that have to do with configuration, content locality, and secret data.

Secrets

Typically with Ansible you are able to provide secret data via a series of mechanisms, many of which are pluggable and configurable. When using Ansible Runner, however, certain considerations need to be made; these are analogous to how Ansible AWX and Tower manage this information.

See Runner Input Directory Hierarchy for more information

Container Names

Like all ansible-runner jobs, each job has an identifier associated with it which is also the name of the artifacts subfolder where results are saved to. When a container for job isolation is launched, it will be given a name of ansible_runner_<job identifier>. Some characters from the job identifier may be replaced with underscores for compatibility with names that Podman and Docker allow.

This name is used internally if a command needs to be ran against the container at a later time (e.g., to stop the container when the job is canceled).