Red Hat Ansible Automation Platform Creator Guide
This guide is intended for developers looking to learn how to use Ansible in creating content for automation.
Chapter 1. Preface
Using automation execution environments to automate content within the Red Hat Ansible Automation Platform
You can use Execution Environments as reproducible, portable, consistent and shareable container images. They control all of the dependencies of an Ansible Automation Platform job’s runtime environment from system dependencies, Python dependencies, Ansible versions, and Ansible content in the form of Collections.
Chapter 2. Introduction to content creator workflows and automation execution environments
2.1. About content workflows
Before Red Hat Ansible Automation Platform 2.0, an automation content developer may have needed so many Python virtual environments that they required their own automation in order to manage them. To reduce this level of complexity, Ansible Automation Platform 2.0 is moving away from virtual environments and using containers, referred to as automation execution environments, instead, as they are straightforward to build and manage and are more shareable across teams and orgs.
As automation controller shifts to using automation execution environments, tools like Automation content navigator and Ansible Builder ensure that you can take advantage of those automation execution environments locally within your own development system.
2.2. Architecture overview
The following list shows the arrangements and uses of tools available on Ansible Automation Platform 2.0, along with how they can be utilized:
- Automation content navigator only — can be used today in Ansible Automation Platform 1.2
- Automation content navigator + downloaded automation execution environments — used directly on laptop/workstation
- Automation content navigator + downloaded automation execution environments + automation controller — for pushing/executing locally → remotely
- Automation content navigator + automation controller + Ansible Builder + Layered custom EE — provides even more control over utilized content for how to execute automation jobs
Chapter 3. Understanding Ansible concepts
As a automation developer, review the following Ansible concepts to create successful Ansible playbooks and automation execution environments before beginning your Ansible development project.
- Ansible is installed. For information about installing Ansible, see Installing Ansible in the Ansible documentation.
3.2. About Ansible Playbooks
Playbooks are files written in YAML that contain specific sets of human-readable instructions, or “plays”, that you send to run on a single target or groups of targets.
Playbooks can be used to manage configurations of and deployments to remote machines, as well as sequence multi-tier rollouts involving rolling updates. Use playbooks to delegate actions to other hosts, interacting with monitoring servers and load balancers along the way. Once written, playbooks can be used repeatedly across your enterprise for automation.
3.3. About Ansible Roles
A role is Ansible’s way of bundling automation content as well as loading related vars, files, tasks, handlers, and other artifacts automatically by utilizing a known file structure.. Instead of creating huge playbooks with hundreds of plays, you can use roles to break the tasks apart into smaller, more discrete units of work.
You can find roles for provisioning infrastructure, deploying applications, and all of the tasks you do every day on Ansible Galaxy. Filter your search by Type and select Role. Once you find a role that you’re interested in, you can download it by using the
ansible-galaxy command that comes bundled with Ansible:
$ ansible-galaxy install username.rolename
3.4. About Content Collections
An Ansible Content Collection is a ready-to-use toolkit for automation. It includes multiple types of content such as playbooks, roles, modules, and plugins all in one place. The diagram below shows the basic structure of collections:
├── docs ├── galaxy.yml ├── playbooks │ ├── files │ ├── tasks │ ├── templates │ └── vars ├── plugins │ ├── modules │ │ ├── module1.py │ │ └── module2.py │ ├── lookups │ └── filters ├── titles │ ├── role1 │ └── role2 └── tests
In Red Hat Ansible Automation Platform, automation hub serves as the source for Ansible Certified Content Collections.
3.5. About Execution Environments
Automation execution environments are consistent and shareable container images that serve as Ansible control nodes. Automation execution environments remediates challenges with Ansible content requiring non-default dependencies.
Automation execution environments contain:
- Ansible Runner
- Ansible Collections
Python and/or system dependencies
- modules/plugins in collections
- custom user needs
You can define and create an automation execution environment using Ansible Builder.
Chapter 4. Tools and components
Learn more about the Red Hat Ansible Automation Platform tools and components you will use in creating automation execution environments.
4.1. About Ansible Builder
Ansible Builder is a command line tool that automates the process of building automation execution environments by using the metadata defined in various Ansible Collections, as well as by the user.
4.3. About Automation Hub
Automation Hub provides a place for Red Hat subscribers to quickly find and use content that is supported by Red Hat and our technology partners to deliver additional reassurance for the most demanding environments.
At a high level, Automation Hub provides an overview of all partners participating and providing certified, supported content.
From a central view, users can dive deeper into each partner and check out the collections.
Additionally, a searchable overview of all available collections is available.
4.4. About the Ansible command line interface
Using Ansible on the command line is a useful way to execute tasks that you don’t repeat very frequently; for repeated tasks, writing a playbook is recommended.
An ad-hoc command for Ansible on the command line follows this structure:
$ ansible [pattern] -m [module] -a "[module options]"
4.5. Additional resources
Chapter 5. Setting up your development environment
You can follow the procedures in this section to set up your development environment to create automation execution environments.
5.1. Installing Ansible Builder
You can install Ansible Builder using Red Hat Subscription Management to register and attach to your Red Hat Ansible Automation Platform subscription. In your terminal, run the following command:
$ dnf install ansible-builder
You can also install Ansible Builder from the Python Package Index (PyPI). To install with this setup, run:
$ pip install ansible-builder
5.3. Downloading base automation execution environments
Base images that ship with AAP 2.0 are hosted on the Red Hat Ecosystem Catalog (registry.redhat.io).
- You have a valid Red Hat Ansible Automation Platform subscription.
Log in to registry.redhat.io
$ podman login registry.redhat.com
Pull the base images from the registry
$ podman pull registry.redhat.io/aap/<image name>
Chapter 6. Creating content
Use the guidelines in this section of the Creator Guide to learn more about the developing the content you will use in Red Hat Ansible Automation Platform.
6.1. Creating playbooks
Playbooks start with the three YAML dashes (---) followed by:
- Name: a brief description of the overall function of the playbook, which assists in keeping it readable and organized for all users.
- Hosts: identifies the target(s) for Ansible to run against.
Become statements: this optional statement can be set to
yesto activate privilege escalation (e.g., sudo, su, pfexec, doas, pbrun, dzdo, ksu, etc.).
- Tasks: this is where actions that get executed via a call to an Ansible module get listed.
--- - name: Set Up a Project and Job Template hosts: host.name.ip become: true tasks: - name: Create a Project awx.awx.project: name: Job Template Test Project state: present scm_type: git scm_url: https://github.com/ansible/ansible-tower-samples.git - name: Create a Job Template awx.awx.job_template: name: my-job-1 project: Job Template Test Project inventory: Demo Inventory playbook: hello_world.yml job_type: run state: present
6.2. Creating roles
ansible-galaxy command line tool that comes bundled with Ansible, you can create a role with the
As an example, the following command will create a role directory structure called
role_name in the current working directory:
$ ansible-galaxy init role_name
The `role_name` directory will contain the following:
.travis.yml README.md defaults/ main.yml files/ handlers/ main.yml meta/ main.yml tasks/ main.yml templates/ tests/ inventory test.yml vars/ main.yml
- For more information on creating roles, see Creating roles in the Ansible Galaxy documentation.
6.3. Creating collections
You can create your own Collections locally with the Ansible Galaxy CLI tool. All of the Collection-specific commands can be activated by using the
- You have Ansible version 2.9 or newer installed in your development environment.
- In your terminal, navigate to where you want your namespace root directory to be.
Run the following command, replacing
my_collection_namewith the values you choose:
$ ansible-galaxy collection init <my_namespace>.<my_collection_name>Note
Make sure you have the proper permissions to upload to a namespace by checking under the "My Content" tab on galaxy.ansible.com or cloud.redhat.com/ansible/automation-hub
The above command will create a directory named from the namespace argument above (if one does not already exist) and then create a directory under that with the Collection name. Inside of that directory will be the default or "skeleton" Collection. This is where you can add your roles or plugins and start working on developing your own Collection.
In relation to execution environments, Collection developers can declare requirements for their content by providing the appropriate metadata via Ansible Builder.
Requirements from a Collection can be recognized in these ways:
meta/execution-environment.ymlreferences the Python and/or
A file named
requirements.txt, which contains information on the Python dependencies and can sometimes be found at the root level of the Collection
A file named
bindep.txt, which contains system-level dependencies and can be sometimes found in the root level of the Collection
If any of these files are in the
build_ignoreof the Collection, Ansible Builder will not pick up on these since this section is used to filter any files or directories that should not be included in the build artifact
Collection maintainers can verify that ansible-builder recognizes the requirements they expect by using the introspect command:
$ ansible-builder introspect --sanitize ~/.ansible/collections/
- For more information on creating collections, see Creating collections in the Ansible Developer Guide.
6.4. Creating automation execution environments
- An automation execution environments definition file will specify
- An Ansible version
- A Python version (defaults to system Python)
- A set of required Python libraries
- Zero or more Content Collections (optional)
- Python dependencies for those specific Collections
The concept of specifying a set of Collections for an environment is to resolve and install their dependencies. The Collections themselves are not required to be installed on the machine that you are generating the automation execution environments on.
An automation execution environments is built from this definition, and results in a container image. Please read the Ansible Builder documentation to learn the steps involved in creating these images.
Chapter 7. Migrating existing content
Use the following sections learn how to use the
awx-manage commmand to assist with additional steps in the migration process once you have upgraded to Red Hat Ansible Automation Platform 2.0 and automation controller 4.0. Additionally, learn more about migrating between versions of Ansible.
7.1. Migrating virtual envs to automation execution environments
Use the following sections to assist with additional steps in the migration process once you have upgraded to Red Hat Ansible Automation Platform 2.0 and automation controller 4.0.
7.1.1. Listing custom virtual environments
You can list the virtual environments on your automation controller instance using the
SSH into your automation controller instance and run:
$ awx-manage list_custom_venvs
A list of discovered virtual environments will appear.
# Discovered virtual environments: /var/lib/awx/venv/testing /var/lib/venv/new_env To export the contents of a virtual environment, re-run while supplying the path as an argument: awx-manage export_custom_venv /path/to/venv
7.1.2. Viewing objects associated with a custom virtual environment
View the organizations, jobs, and inventory sources associated with a custom virtual environment using the
SSH into your automation controller instance and run:
$ awx-manage custom_venv_associations /path/to/venv
A list of associated objects will appear.
inventory_sources: - id: 15 name: celery job_templates: - id: 9 name: Demo Job Template @ 2:40:47 PM - id: 13 name: elephant organizations - id: 3 name: alternating_bongo_meow - id: 1 name: Default projects: 
7.1.3. Selecing the custom virtual environment to export
Select the custom virtual environment you wish to export using
awx-manage export_custom_venv command.
SSH into your automation controller instance and run:
$ awx-manage export_custom_venv /path/to/venv
The output from this command will show a
pip freeze of what is in the specified virtual environment. This information can be copied into a
requirements.txt file for Ansible Builder to use for creating a new automation execution environments image
numpy==1.20.2 pandas==1.2.4 python-dateutil==2.8.1 pytz==2021.1 six==1.16.0 To list all available custom virtual environments run: awx-manage list_custom_venvs
-q flag when running `awx-manage list_custom_venvs`to reduce output.
7.2. Migrating between Ansible Core versions
Migrating between versions of Ansible Core requires you to update your playbooks, plugins and other parts of your Ansible infrastructure to ensure they work with the latest version. This process requires that changes are validated against the updates made to each successive version of Ansible Core. If you intend to migrate from Ansible 2.9 to Ansible 2.11, you first need to verify that you meet the requirements of Ansible 2.10, and from there make updates to 2.11.
7.2.1. Ansible Porting Guides
The Ansible Porting Guide is a series of documents that provide information on the behavioral changes between consecutive Ansible versions. Refer to the guides when migrating from version of Ansible to a newer version.
7.2.2. Additional resources
Chapter 9. Conclusion
You should now be able to customize an automation execution environments for your particular automation needs, as well as share and use them via a container registry.