.. _execution_environments:
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: :ref:`standalone`)
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.
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 :ref:`inputdir` 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_``. 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).
~/.ssh/ symlinks
^^^^^^^^^^^^^^^^
In order to make the ``run`` container execution of Ansible
easier, Ansible Runner will automatically bind mount your local ssh agent
UNIX-domain socket (``SSH_AUTH_SOCK``) into the container runtime. However, this
does not work if files in your ``~/.ssh/`` directory happen to be symlinked to
another directory that is also not mounted into the container runtime. The Ansible
Runner ``run`` subcommand provides the ``--container-volume-mount``
option to address this, among other things.
Here is an example of an ssh config file that is a symlink:
::
$ $ ls -l ~/.ssh/config
lrwxrwxrwx. 1 myuser myuser 34 Jul 15 19:27 /home/myuser/.ssh/config -> /home/myuser/dotfiles/ssh_config
$ ansible-runner run \
--container-volume-mount /home/myuser/dotfiles/:/home/myuser/dotfiles/ \
--process-isolation --process-isolation-executable podman \
/tmp/private --playbook my_playbook.yml -i my_inventory.ini