Getting Started Ee

Building your first Execution Environment

We are going to build an EE that represents an Ansible control node containing standard packages such as ansible-core and Python in addition to an Ansible collection (community.postgresql) and its dependency (the psycopg2-binary Python connector).

To build your first EE:

  1. Create a project folder on your filesystem.

    mkdir my_first_ee && cd my_first_ee

  2. Create a execution-environment.yml file that specifies dependencies to include in the image.

    yaml/execution-environment.yml

    [!NOTE] The psycopg2-binary Python package is included in the requirements.txt file for the collection. For collections that do not include requirements.txt files, you need to specify Python dependencies explicitly. See the Ansible Builder documentation for details.

  3. Build a EE container image called postgresql_ee.

    If you use docker, add the --container-runtime docker argument.

    ansible-builder build --tag postgresql_ee

  4. List container images to verify that you built it successfully.

    podman image list

localhost/postgresql_ee          latest      2e866777269b  6 minutes ago  1.11 GB

You can verify the image you created by inspecting the Containerfile or Dockerfile in the context directory to view its configuration.

less context/Containerfile

You can also use Ansible Navigator to view detailed information about the image.

Run the ansible-navigator command, type :images in the TUI, and then choose postgresql_ee.

Proceed to running_custom_execution_environment and test the EE you just built.

Running a local container registry for Execution Environments
This guide in the Ansible community forum explains how to set up a local registry for your Execution Environment images.

Getting started with Execution Environments

You can run Ansible automation in containers, like any other modern software application. Ansible uses container images known as Execution Environments (EE) that act as control nodes. EEs remove complexity to scale out automation projects and make things like deployment operations much more straightforward.

An Execution Environment image contains the following packages as standard:

In addition to the standard packages, an EE can also contain:

This getting started guide shows you how to build and test a simple Execution Environment. The resulting container image represents an Ansible control node that contains:

introduction setup_environment build_execution_environment run_execution_environment run_community_ee_image

Introduction to Execution Environments

Ansible Execution Environments aim to resolve complexity issues and provide all the benefits you can get from containerization.

Reducing complexity

There are three main areas where EEs can reduce complexity:

Dependencies

Software applications typically have dependencies, and Ansible is no exception. These dependencies can include software libraries, configuration files or other services, to name a few.

Traditionally, administrators install application dependencies on top of an operating system using packaging management tools such as RPM or Python-pip. The major drawback of such an approach is that an application might require versions of dependencies different from those provided by default. For Ansible, a typical installation consists of ansible-core and a set of Ansible collections. Many of them have dependencies for the plugins, modules, roles and playbooks they provide.

The Ansible collections can depend on the following pieces of software and their versions:

The dependencies have to be installed and sometimes can conflict with each other.

One way to partially resolve the dependency issue is to use Python virtual environments on Ansible control nodes. However, applied to Ansible, virtual environments have drawbacks and natural limitations.

Portability

An Ansible user writes content for Ansible locally and wants to leverage the container technology to make their automation runtimes portable, shareable and easily deployable to testing and production environments.

Content separation

In situations when there is an Ansible control node or a tool such as Ansible AWX/Controller used by several users, they might want separate their content to avoid configuration and dependency conflicts.

Ansible tooling for EEs

Projects in the Ansible ecosystem also provide several tools that you can use with EEs, such as:

Ready to get started with EEs? Proceed to setting_up_ee_environment.

Running Ansible with the community EE image

You can run ansible without the need to build a custom EE using community images.

Use the community-ee-minimal image that includes only ansible-core or the community-ee-base image that also includes several base collections. Run the following command to see the collections included in the community-ee-base image:

ansible-navigator collections --execution-environment-image ghcr.io/ansible-community/community-ee-base:latest

Run the following Ansible ad-hoc command against localhost inside the community-ee-minimal container:

ansible-navigator exec "ansible localhost -m setup" --execution-environment-image ghcr.io/ansible-community/community-ee-minimal:latest --mode stdout

Now, create a simple test playbook and run it against localhost inside the container:

yaml/test_localhost.yml

ansible-navigator run test_localhost.yml --execution-environment-image ghcr.io/ansible-community/community-ee-minimal:latest --mode stdout

Running your EE

You can run your EE on the command line against localhost or a remote target using ansible-navigator.

[!NOTE] There are other tools besides ansible-navigator you can run EEs with.

Run against localhost

  1. Create a test_localhost.yml playbook.

    yaml/test_localhost.yml

  2. Run the playbook inside the postgresql_ee EE.

    ansible-navigator run test_localhost.yml --execution-environment-image postgresql_ee --mode stdout --pull-policy missing

You may notice the facts being gathered are about the container and not the developer machine. This is because the ansible playbook was run inside the container.

Run against a remote target

Before you start, ensure you have the following:

Execute a playbook inside the postgresql_ee EE against a remote host machine as in the following example:

  1. Create a directory for inventory files.

    mkdir inventory

  2. Create the hosts.yml inventory file in the inventory directory.

    yaml/hosts.yml

  3. Create a test_remote.yml playbook.

    yaml/test_remote.yml

  4. Run the playbook inside the postgresql_ee EE.

    Replace student with the appropriate username. Some arguments in the command can be optional depending on your target host authentication method.

    ansible-navigator run test_remote.yml -i inventory --execution-environment-image postgresql_ee:latest --mode stdout --pull-policy missing --enable-prompts -u student -k -K

Execution Environment Definition
Provides information about the about Execution Environment definition file and available options.

Ansible Builder CLI usage
Provides details about using Ansible Builder.

Ansible Navigator documentation
Provides details about using Ansible Navigator.

Running a local container registry for EEs
This guide in the Ansible community forum explains how to set up a local registry for your Execution Environment images.

Setting up your environment

Complete the following steps to set up a local environment for your first Execution Environment:

  1. Ensure the following packages are installed on your system:

    • podman or docker
    • python3
    • python3-pip

    If you use the DNF package manager, install these prerequisites as follows:

    sudo dnf install -y podman python3 python3-pip

  2. Install ansible-navigator:

    pip3 install ansible-navigator

    Installing ansible-navigator lets you run EEs on the command line. It includes the ansible-builder package to build EEs.

    If you want to build EEs without testing, install only ansible-builder:

    pip3 install ansible-builder

  3. Verify your environment with the following commands:

    ansible-navigator --version
ansible-builder --version

Ready to build an EE in a few easy steps? Proceed to building_execution_environment.

Want to try an EE without having to build one? Proceed to running_community_execution_environment.