AWX in Action

The Building Blocks: Custom EE, Project, and Job Templates

In practice, you'll likely need to build a custom execution environment to run your playbooks. This is especially true if you're using roles from Ansible Galaxy or collections from Ansible Hub. There are other ways to do the same thing without building a custom execution environment each time, but this is the cleanest and most repeatable approach.

Imagine we want to deploy and configure a PostgreSQL database. Instead of writing the roles from scratch, we can use a community role from Ansible Galaxy. As an example, we'll use the geerlingguy.postgresql role to deploy and configure PostgreSQL.

Step 1, Build a custom execution environment and a playbook:

First, we need to build a custom execution environment that includes the required dependencies to run the role and the role itself. We'll use the ansible-builder tool to build the execution environment.

The only required dependency for the geerlingguy.postgresql role is the community.postgresql collection. We'll also include the ansible-core and ansible-runner packages in the execution environment.

In the following example, it's assumed that you have a Docker Hub account and have logged in using the docker login command. Replace $DOCKERHUB_USERNAME with your Docker Hub username.

Install Docker if you haven't already:

# Install Docker if you didn't already
curl -fsSL https://get.docker.com -o get-docker.sh
bash get-docker.sh --version 29.4.3

# Enable and start Docker:
systemctl enable --now docker

Start by exporting your Docker Hub username:

export DOCKERHUB_USERNAME=

Log in to Docker Hub if you haven't already:

docker login -u $DOCKERHUB_USERNAME

Notes:

• If you want to use a different registry, adjust the commands accordingly.
• If you prefer to use Podman instead of Docker, set the container-runtime option to podman in the ansible-builder command below.

Let's continue by building a custom execution environment that includes all necessary dependencies and pushing it to Docker Hub.

Create a directory for the execution environment:

mkdir -p $HOME/ansible/execution-environments/postgresql

Change to the directory:

cd $HOME/ansible/execution-environments/postgresql

Install python3-venv if you haven't already:

dnf install -y python3-pip
pip install virtualenv

Create a virtual environment:

python3 -m venv venv

Activate the virtual environment:

source venv/bin/activate

Install ansible-builder:

pip install ansible-builder==3.1.1

Create the execution-environment.yml file:

cat < execution-environment.yml
---
version: 3

images:
  base_image:
    name: quay.io/centos/centos:stream9

dependencies:
  ansible_core:
    package_pip: ansible-core==2.15.0
  ansible_runner:
    package_pip: ansible-runner      
  galaxy: requirements.yml
  system: bindep.txt
EOF

Create the bindep.txt file to add the necessary system packages:

cat < bindep.txt
openssh-clients
EOF

Create the "requirements.yml" file:

cat < requirements.yml
---
roles:
  - name: geerlingguy.postgresql
    version: 3.5.2
collections:
  - name: community.postgresql
    version: 3.4.1
EOF

Build the execution environment:

ansible-builder build \
  --file=execution-environment.yml \
  --tag=$DOCKERHUB_USERNAME/my-custom-ee:postgresql \
  --container-runtime=docker \
  --verbosity=3 \
  --no-cache

Push the image to Docker Hub:

docker push $DOCKERHUB_USERNAME/my-custom-ee:postgresql

Create a new directory for the playbook:

mkdir -p /data/projects/postgresql/

Create the playbook:

cat < /data/projects/postgresql/main.yml
---
- hosts: all
  roles:
    - geerlingguy.postgresql
  vars_files:
    - vars/main.yml
EOF

Create the vars folder:

mkdir -p /data/projects/postgresql/vars

Create the vars/main.yml file:

cat < /data/projects/postgresql/vars/main.yml
---
postgresql_databases:
  - name: "{{ database_name }}"