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.
Making open source more inclusive
Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. Because of the enormity of this endeavor, these changes will be implemented gradually over several upcoming releases. For more details, see our CTO Chris Wright’s message.
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 tasks, you can use roles to break the tasks apart into smaller, more discrete and composable 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 role 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 a collection:
collection/ ├── docs/ ├── galaxy.yml ├── meta/ │ └── runtime.yml ├── plugins/ │ ├── modules/ │ │ └── module1.py │ ├── inventory/ │ ├── lookup/ │ ├── filter/ │ └── .../ ├── README.md ├── roles/ │ ├── role1/ │ ├── role2/ │ └── .../ ├── playbooks/ │ ├── files/ │ ├── vars/ │ ├── templates/ │ ├── playbook1.yml │ └── tasks/ └── tests/ ├── integration/ └── unit/
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 reduce the challenge of sharing Ansible content that has external dependencies.
Automation execution environments contain:
- Ansible Core
- Ansible Runner
- Ansible Collections
- Python libraries
- System dependencies
- 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.2. Uses for Automation content navigator
Automation content navigator is a command line, content-creator-focused tool with a text-based user interface. You can use Automation content navigator to:
- Launch and watch jobs and playbooks.
- Share stored, completed playbook and job run artifacts in JSON format.
- Browse and introspect automation execution environments.
- Browse your file-based inventory.
- Render Ansible module documentation and extract examples you can use in your playbooks.
You cannot execute Ansible commands that are part of Ansible core, such as
ansible-playbook, in containers such as automation execution environments. Use Automation content navigator which includes a set of the Ansible CLI commands that are compatible with automation execution environments. Automation content navigator also includes a more detailed output within its text-based user interface.
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
- For more information on how to use Ansible as a command line tool, refer to working with command line tools in the Ansible User Guide.
- To upload content to automation hub, see Uploading content to automation hub in the Ansible Automation Platform prodcut documentation.
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 (RHSM) to attach your Red Hat Ansible Automation Platform subscription. Attaching your Red Hat Ansible Automation Platform subscription allows you to access subscription-only resources necessary to install
ansible-builder. Once you attach your subscription, the necessary repository for
ansible-builder is automatically enabled.
You must have valid subscriptions attached on the host before installing
In your terminal, run the following command to activate your Ansible Automation Platform repo:
$ dnf config-manager --enable ansible-automation-platform-2.1-for-rhel-8-x86_64-rpms
Then enter the following command to install Ansible Builder:
$ dnf install ansible-builder
5.2. Installing Automation content navigator on RHEL from an RPM
You can install Automation content navigator on Red Hat Enterprise Linux (RHEL) from an RPM.
- You have installed RHEL 8 or later.
- You registered your system with Red Hat Subscription Manager.
Attach the Red Hat Ansible Automation Platform SKU.
$ subscription-manager attach --pool=<sku-pool-id>
Enable the repository for RHEL 8.
$ sudo subscription-manager repos --enable ansible-automation-platform-2.1-for-rhel-8-x86_64-rpms
Install Automation content navigator.
$ dnf install ansible-navigator
Verify your Automation content navigator installation:
$ ansible-navigator --help
The following example demonstrates a successful installation:
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 contain one or more plays. A basic play contains the following sections:
- 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 enable privilege escalation using a become plugin (such as
- Tasks: this is the list actions that get executed against each host in the play.
- 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 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. For simplicity, this should be a path in COLLECTIONS_PATH but that is not required.
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.3. Creating roles
You can create roles using the Ansible Galaxy CLI tool. Role-specific commands can be accessed from the
ansible-galaxy role init <role_name>
Standalone roles outside of Collections are still supported, but new roles should be created inside of a Collection to take advantage of all the features Ansible Automation Platform has to offer.
In your terminal, navigate to the
rolesdirectory inside a collection.
Create a role called
role_nameinside the collection created previously:
$ ansible-galaxy role init my_role
The collection now contains a role named
~/.ansible/collections/ansible_collections/<my_namespace>/<my_collection_name> ... └── roles/ └── my_role/ ├── .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
A custom role skeleton directory can be supplied using the
--role-skeletonargument. This allows organizations to create standardized templates for new roles to suit their needs.
ansible-galaxy role init my_role --role-skeleton ~/role_skeleton
This will create a role named
my_role by copying the contents of
my_role. The contents of
role_skeleton can be any files or folders that are valid inside a role directory.
- For more information on creating roles, see Creating roles in the Ansible Galaxy documentation.
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 command 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. Selecting 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
- Refer to the Ansible 2.9 for behavior changes between Ansible 2.8 and Ansible 2.9.
- Refer to the Ansible 2.10 for behavior changes between Ansible 2.9 and Ansible 2.10.
Chapter 8. Executing your content with Automation content navigator
Now that you have your automation execution environments built, you can use Ansible content navigator in order to validate that the content will be run in the same manner as the automation controller will run it.
8.1. Running Ansible playbooks with Automation content navigator
As a content creator, you can execute your Ansible playbooks with Automation content navigator and interactively delve into the results of each play and task to verify or troubleshoot the playbook. You can also execute your Ansible playbooks inside an execution environment and without an execution environment to compare and troubleshoot any problems.
8.1.1. Executing a playbook from Automation content navigator
You can run Ansible playbooks with the Automation content navigator text-based user interface to follow the execution of the tasks and delve into the results of each task.
- A playbook.
A valid inventory file if not using
localhostor an inventory plugin.
Start Automation content navigator
Run the playbook.
ansible-navigator run simple-playbook.yml -i inventory.ymlto run the playbook.
Verify or add the inventory and any other command line parameters.
INVENTORY OR PLAYBOOK NOT FOUND, PLEASE CONFIRM THE FOLLOWING ───────────────────────────────────────────────────────────────────────── Path to playbook: /home/ansible-navigator_demo/simple_playbook.yml Inventory source: /home/ansible-navigator-demo/inventory.yml Additional command line parameters: Please provide a value (optional) ────────────────────────────────────────────────────────────────────────── Submit Cancel
Submitand hit Enter. You should see the tasks executing.
Type the number next to a play to step into the play results, or type
:<number>for numbers above 9.
Notice failed tasks show up in red if you have colors enabled for Automation content navigator.
Type the number next to a task to review the task results, or type
:<number>for numbers above 9.
:docbring up the documentation for the module or plugin used in the task to aid in troubleshooting.
ANSIBLE.BUILTIN.PACKAGE_FACTS (MODULE) 0│--- 1│doc: 2│ author: 3│ - Matthew Jones (@matburt) 4│ - Brian Coca (@bcoca) 5│ - Adam Miller (@maxamillion) 6│ collection: ansible.builtin 7│ description: 8│ - Return information about installed packages as facts. <... output omitted ...> 11│ module: package_facts 12│ notes: 13│ - Supports C(check_mode). 14│ options: 15│ manager: 16│ choices: 17│ - auto 18│ - rpm 19│ - apt 20│ - portage 21│ - pkg 22│ - pacman <... output truncated ...>
8.1.2. Reviewing playbook results with an Automation content navigator artifact file
Automation content navigator saves the results of the playbook run in a JSON artifact file. You can use this file to share the playbook results with someone else, save it for security or compliance reasons, or review and troubleshoot later. You only need the artifact file to review the playbook run. You do not need access to the playbook itself or inventory access.
- A Automation content navigator artifact JSON file from a playbook run.
Start Automation content navigator with the artifact file.
$ ansible-navigator replay simple_playbook_artifact.json
Review the playbook results that match when the playbook ran.
You can now type the number next to the plays and tasks to step into each to review the results, as you would after executing the playbook.
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.