Skip to content

ansiblejunky/ansible-execution-environment

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

42 Commits
.config
.config
 
 
.github/workflows
.github/workflows
 
 
files
files
 
 
.gitignore
.gitignore
 
 
LICENSE
LICENSE
 
 
Makefile
Makefile
 
 
README.md
README.md
 
 
Vagrantfile
Vagrantfile
 
 
ansible-navigator.yml
ansible-navigator.yml
 
 
execution-environment.yml
execution-environment.yml
 
 

Repository files navigation

Ansible Execution Environments Demo

Basic information to help you get familiar with Ansible Execution Environments and the latest Ansible Automation Platform.

General information on Ansible Controller and the related execution environments.

Quick Start

  • Start Vagrant machine vagrant up
  • Login to Vagrant machine vagrant ssh
  • Prepare environment: source ~/ansible/bin/activate && cd /vagrant
  • Edit dependency files: requirements.yml, requirements.txt, bindep.txt
  • Update tokens
    • Generate tokens from Galaxy and Automation Hub
    • Set environment variables with token values (See below)
  • Edit execution-environment.yml accordingly
  • Edit Makefile
    • Change the tag (v4, v5, etc) to build a new version
  • Login to source registry podman login ...
  • Build it make build
  • Publish it make publish
  • Destroy Vagrant machine vagrant destroy
  • Enjoy your day

Requirements

Build server

This repository uses vagrant to spin up a RHEL server and then provisions it.

Tokens

To access the Ansible content (collections) and build execution environments, you'll need to provide authentication using a token. This is configured within the ansible.cfg in the root folder. To generate this file, use the template ansible.cfg.template which authenticates to both Automation Hub and Ansible Galaxy. This means we will always pull from Automation Hub first, but if not found we default to using Ansible Galaxy for content.

First, set the following environment variables with the appropriate token strings. And then use the envsubst command to generate the necessary ansible.cfg file.

# Automation Hub token https://console.redhat.com/ansible/automation-hub/token
export ANSIBLE_GALAXY_SERVER_AUTOMATION_HUB_TOKEN=
# Ansible Galaxy token https://galaxy.ansible.com/ui/token/
export ANSIBLE_GALAXY_SERVER_RELEASE_GALAXY_TOKEN=

# Generate ansible.cfg file
envsubst < files/ansible.cfg.template > ./ansible.cfg

Image registry

Ensure you login to the registry of choice using podman/docker command podman login <registry_url>

Automation Hub Registry (hub.example.com):

  • Ensure docker/podman is authorized to access registry since Automation Hub uses self-signed certificates (see info at bottom of this article)
  • Run the CLI login command podman login hub.example.com:443

Quay Registry (quay.io):

  • Ensure you authorize docker/podman with this registry
  • Go to https://quay.io/ and login or create an account
  • Navigate to top-right for Account Settings
  • Select the tool icon on the left
  • Set the Docker/Podman CLI Password to enable encrypted passwords
  • Generate the encryped password (re-enter the password)
  • Select the option "Docker Login" or "Podman Login" to get the CLI command
  • Run the CLI login command to have docker/podman authorized to pull/push images

Red Hat Registry (registry.redhat.io):

Docker Hub (hub.docker.com):

  • Create a free account on the website
  • Login to the website
  • Run the CLI login command docker login with your credentials

Pull the Image

Now that you have authenticated with a registry, you can pull down images from that registry. For example, you might want to pull down the Ansible base images. You can find official Ansible container images using https://catalog.redhat.com/software/containers/search.

# Pull base images for Ansible from registry.redhat.io
podman pull registry.redhat.io/ansible-automation-platform-24/ee-29-rhel8:latest
podman pull registry.redhat.io/ansible-automation-platform-24/ee-minimal-rhel8:latest
podman pull registry.redhat.io/ansible-automation-platform-24/ee-supported-rhel8:latest

# Pull images from hub.docker.com
podman login hub.docker.com
podman pull hello-world
podman run hello-world

Build the Image

Ansible playbooks will be executed from a container image. We define our "golden" image using a build definition file named execution-environment.yml. The image is built using that template file and running the ansible-builder tool.

Let's first define our execution environment using yaml. Here is an example file from this repository.

Now let's run ansible-builder to create the image based on our template. Note that Podman is used by default to build images but we will use Docker instead. Also the default name and tag for the container image being built is ansible-execution-env:latest but it's highly recommended that you avoid using "latest" and set your own tag/version using the --tag argument.

# Set tokens using environment variables
export ANSIBLE_GALAXY_SERVER_AUTOMATION_HUB_TOKEN="token_value"
export ANSIBLE_GALAXY_SERVER_COMMUNITY_TOKEN="token_value"

# Generate ansible.cfg using template
envsubst < files/ansible.cfg.template > ./ansible.cfg

# Test tokens
mkdir collections
ansible-galaxy collection download -r requirements.yml -p collections/
rm -rf collections

# Build the image and tag the image
ansible-builder build --verbosity 3 --container-runtime=podman --tag ansible-ee:5.0
# List images
$ podman image list
REPOSITORY                            TAG             IMAGE ID       CREATED         SIZE
ansible-ee                 5.0             9fec21fe39be   2 hours ago     987MB

Scan the Image

It's important to scan your image for vulnerabilities. Below are a couple articles showing how to do that. The recommendation is to implement this inside the Makefile in this repository so you can run it easily as part of your pipeline.

Test the Image

We can test that everything is working by running an Ansible Playbook in the image using ansible-navigator. The tool launches the container, runs the playbook and shows an interactive screen where you can watch the playbook run through. To quit the tool, use similar mechanism :q! like within a vi editor.

# Run playbook to test basic operations against new image
ansible-navigator run playbook.yml --container-engine podman --execution-environment-image ansible-ee:5.0

# Check configuration of new image
ansible-navigator config --container-engine podman --execution-environment-image ansible-ee:5.0

Publish the Image

Once you have built the image locally, tested it, and scanned it for security issues - you are now ready to publish the image to a registry of choice.

# Example using quay.io
podman login quay.io
podman tag ansible-ee:5.0 quay.io/jwadleig/ansible-ee:5.0
podman push quay.io/jwadleig/ansible-ee:5.0

# Example using onprem Automation Hub
podman login hub.example.com:443
podman tag ansible-ee:6.0 hub.example.com:443/ansible-ee
podman push hub.example.com:443/ansible-ee --remove-signatures

Tips and Tricks

Building:

Migration of Python Virtual Environments:

Ansible Collection issues:

Python dependency issues:

  • Install johnnydep inside your current venv and leverage the tool to check various dependencies for python modules that might be causing issues. For example johnnydep requests.

Image building and customization:

Pipelines:

Ansible Navigator:

  • Default execution environment that ansible-navigator uses when not specified: quay.io/ansible/creator-ee
  • Examine execution environment using ansible-navigator: ansible-navigator --eei <image-name>
  • Extract list of collections from existing execution environment: ansible-navigator --eei <image-name> collections --mode stdout
  • Use Credentials within ansible-navigator tool:
  • How to run --syntax-check using ansible-navigator:
ansible-navigator run <playbook> --syntax-check --mode stdout`
  • Start shell session inside container image:
podman run -it registry.redhat.io/ansible-automation-platform-24/ee-minimal-rhel9:latest /bin/bash
  • Run adhoc commands inside image:
podman run --rm <image-name> <command>
  • Change the yum and pip repositories within the base images:
# Create yum repository file locally
cat > ubi.repo <<EOF
[rhel-8-for-x86_64-appstream-rpms]
baseurl = http://x.x.x.x/rpms/rhel-8-for-x86_64-appstream-rpms
gpgkey = file:///etc/pki/rpm-gpg/RPM-GPG-KEY-redhat-release
[rhel-8-for-x86_64-baseos-rpms]
baseurl = http://x.x.x.x/rpms/rhel-8-for-x86_64-baseos-rpms
gpgkey = file:///etc/pki/rpm-gpg/RPM-GPG-KEY-redhat-release
EOF

# Create pip configuration file locally
cat > pip.conf <<EOF
[global]
index-url = https://artifactory.acme.com/artifactory/api/pypi/pypi/simple
trusted-host = artifactory.acme.com
EOF

# Then run the containers
podman run -d -it --name custom-ee-supported registry.redhat.io/ansible-automation-platform-24/ee-supported-rhel8:latest /bin/bash
podman run -d -it --name custom-ee-builder registry.redhat.io/ansible-automation-platform-24/ansible-builder-rhel8:latest /bin/bash

# Then copy the yum repo file into the containers
podman cp ubi.repo custom-ee-supported:/etc/yum.repos.d/
podman cp ubi.repo custom-ee-builder:/etc/yum.repos.d/

# Then copy the pip config file to set the global pip configuration https://pip.pypa.io/en/stable/topics/configuration/
podman cp pip.conf custom-ee-supported:/etc/
podman cp pip.conf custom-ee-builder:/etc/

#Then stop the containers
podman stop -a

#Then commit the containers
podman commit --message "Replaced yum repos" --author "ACME Company" <containerID> <image>

#Then push the containers
podman push <image-name> quay.io/username/myimage
  • Search for images

The following example searches for images and then checks collections, system packages and python packages manually before we run the ansible-builder command.

# Login to vagrant build server
vagrant ssh
source ~/ansible/bin/activate
cd /vagrant

# Login to registry
podman login registry.redhat.io
# Search registry to find latest images
# https://docs.podman.io/en/stable/markdown/podman-search.1.html
podman search ansible-automation-platform-24

# Pull image and start container
podman run -it --rm registry.redhat.io/ansible-automation-platform-24/ee-minimal-rhel9:latest /bin/bash

# Check dependencies for collections
ansible-galaxy collection install -r requirements.yml
cd /home/runner/.ansible/collections/ansible_collections/
grep -R python39 * | grep bindep.txt
grep -R suds *
# Look at potential newer versions of the collections
ansible-galaxy collection install --upgrade -r requirements.yml

# Install windows packages
microdnf install krb5-libs krb5-workstation krb5-devel
# Install Python 3.8 developer tools
microdnf install vi git rsync unzip tar sudo gcc openssl openssl-devel gcc-c++ dnf libpq-devel python38-devel glibc-headers libcurl-devel libssh-devel jq python3-Cython python3-devel openldap-devel
# Install Python 3.9 developer tools
microdnf install vi git rsync unzip tar sudo gcc openssl openssl-devel gcc-c++ dnf libpq-devel python39-devel glibc-headers libcurl-devel libssh-devel jq python3-Cython python3-devel openldap-devel
# Test the installation of required python libraries
pip3 install -r requirements.txt

Tools

ansible-builder:

ansible-navigator:

ansible-bender:

ansible-bender is a tool which bends containers using Ansible playbooks and turns them into container images. It has a pluggable builder selection — it is up to you to pick the tool which will be used to construct your container image. Right now the only supported builder is buildah. More to come in the future. Ansible-bender (ab) relies on Ansible connection plugins for performing builds.

buildah:

buildah is a tool that facilitates building Open Container Initiative (OCI) container images. The Buildah package provides a command line tool that can be used to:

  • create a working container, either from scratch or using an image as a starting point
  • create an image, either from a working container or via the instructions in a Dockerfile
  • images can be built in either the OCI image format or the traditional upstream docker image format
  • mount a working container's root filesystem for manipulation
  • unmount a working container's root filesystem
  • use the updated contents of a container's root filesystem as a filesystem layer to create a new image
  • delete a working container or an image
  • rename a local container

podman:

skopeo:

References

General:

Execution Environments:

Makefiles:

License

GNU General Public License v3.0

Author

John Wadleigh

About

Example of creating and using an Ansible execution environment

Resources

Readme

License

GPL-3.0 license
Activity

Stars

4 stars

Watchers

2 watching

Forks

1 fork
Report repository

Releases

No releases published

Packages

No packages published

Languages