Red Hat Ansible Automation Platform Creator Guide

Red Hat Ansible Automation Platform 2.1

This guide is intended for developers looking to learn how to use Ansible in creating content for automation.

Red Hat Customer Content Services


Providing Feedback:
If you have a suggestion to improve this documentation, or find an error, please contact technical support at to create an issue on the Ansible Automation Platform Jira project using the Docs component.

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.

3.1. Prerequisites

  • 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:

├── docs/
├── galaxy.yml
├── meta/
│   └── runtime.yml
├── plugins/
│   ├── modules/
│   │   └──
│   ├── inventory/
│   ├── lookup/
│   ├── filter/
│   └── .../
├── 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

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 ansible-builder.


  1. 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
  2. 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.


  1. Attach the Red Hat Ansible Automation Platform SKU.

    $ subscription-manager attach --pool=<sku-pool-id>
  2. Enable the repository for RHEL 8.

    $ sudo subscription-manager repos --enable ansible-automation-platform-2.1-for-rhel-8-x86_64-rpms
  3. Install Automation content navigator.

    $ dnf install ansible-navigator


  • Verify your Automation content navigator installation:

    $ ansible-navigator --help

The following example demonstrates a successful installation:

navigator stdout

5.3. Downloading base automation execution environments

Base images that ship with AAP 2.0 are hosted on the Red Hat Ecosystem Catalog (


  • You have a valid Red Hat Ansible Automation Platform subscription.


  1. Log in to

    $ podman login
  2. Pull the base images from the registry

    $ podman pull<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 true/yes to enable privilege escalation using a become plugin (such as sudo, su, pfexec, doas, pbrun, dzdo, ksu).
  • Tasks: this is the list actions that get executed against each host in the play.

Example playbook

- name: Set Up a Project and Job Template
  become: true

    - name: Create a Project
        name: Job Template Test Project
        state: present
        scm_type: git

    - name: Create a 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 collection subcommand.


  • You have Ansible version 2.9 or newer installed in your development environment.


  1. 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.
  2. Run the following command, replacing my_namespace and my_collection_name with the values you choose:

    $ ansible-galaxy collection init <my_namespace>.<my_collection_name>

    Make sure you have the proper permissions to upload to a namespace by checking under the "My Content" tab on or

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:

  • A file meta/execution-environment.yml references the Python and/or bindep requirements files
  • 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_ignore of 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/

Additional resources

  • 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 roles subcommand.

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.


  1. In your terminal, navigate to the roles directory inside a collection.
  2. Create a role called role_name inside the collection created previously:

    $ ansible-galaxy role init my_role

    The collection now contains a role named my_role inside the roles directory:

    └── roles/
        └── my_role/
            ├── .travis.yml
            ├── defaults/
            │   └── main.yml
            ├── files/
            ├── handlers/
            │   └── main.yml
            ├── meta/
            │   └── main.yml
            ├── tasks/
            │   └── main.yml
            ├── templates/
            ├── tests/
            │   ├── inventory
            │   └── test.yml
            └── vars/
                └── main.yml
  3. A custom role skeleton directory can be supplied using the --role-skeleton argument. 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 ~/role_skeleton into my_role. The contents of role_skeleton can be any files or folders that are valid inside a role directory.

Additional resources

  • 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 awx-manage command.


  1. SSH into your automation controller instance and run:

    $ awx-manage list_custom_venvs

A list of discovered virtual environments will appear.

# Discovered virtual environments:

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 awx-manage command.


  1. SSH into your automation controller instance and run:

    $ awx-manage custom_venv_associations /path/to/venv

A list of associated objects will appear.

- id: 15
  name: celery
- id: 9
  name: Demo Job Template @ 2:40:47 PM
- id: 13
  name: elephant
- 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.


  1. 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


To list all available custom virtual environments run:
awx-manage list_custom_venvs

Pass the -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 localhost or an inventory plugin.


  1. Start Automation content navigator

    $ ansible-navigator
  2. Run the playbook.

    $ :run
  3. Optional: type ansible-navigator run simple-playbook.yml -i inventory.yml to run the playbook.
  4. Verify or add the inventory and any other command line parameters.

       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
  5. Tab to Submit and hit Enter. You should see the tasks executing.

    navigator play list
  6. Type the number next to a play to step into the play results, or type :<number> for numbers above 9.

    navigator task list

    Notice failed tasks show up in red if you have colors enabled for Automation content navigator.

  7. Type the number next to a task to review the task results, or type :<number> for numbers above 9.

    navigator task output failed
  8. Optional: type :doc bring up the documentation for the module or plugin used in the task to aid in troubleshooting.

      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
    1. Review the playbook results that match when the playbook ran.

      navigator artifact replay

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.

Legal Notice

Copyright © 2022 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.