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.
Abstract
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 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
- Ansible Runner
- Ansible Collections
Python and/or system dependencies
- modules/plugins in collections
-
content in
ansible-core
- 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. About Automation content navigator
Automation content navigator is a command line, content creator focused tool with a text-based user interface that allows you 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.
4.2.1. Why use Automation content navigator?
Currently, the Ansible commands that are part of Ansible core, such as the ansible-playbook
command, cannot execute in containers. To fill this need, Automation content navigator enables a set of these Ansible CLI commands within automation execution environments. Automation content navigator 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 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.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.
Prerequisites
- You registered your system with Red Hat Subscription Manager.
Procedure
Enable the repository for RHEL 8.
$ sudo subscription-manager repos --enable ansible-automation-platform-2.0-early-access-for-rhel-8-x86_64-rpms
Install Automation content navigator.
$ dnf install ansible-navigator
Verification
Verify your Automation content navigator installation:
$ ansible-navigator --help
You should see the help output describing the main functions of Automation content navigator.
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).
Prerequisites
- You have a valid Red Hat Ansible Automation Platform subscription.
Procedure
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
true
/yes
to 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.
Example playbook
--- - 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
Using the ansible-galaxy
command line tool that comes bundled with Ansible, you can create a role with the init
command.
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
Additional resources
- 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 collection
subcommand.
Prerequisites
- You have Ansible version 2.9 or newer installed in your development environment.
Procedure
- In your terminal, navigate to where you want your namespace root directory to be.
Run the following command, replacing
my_namespace
andmy_collection_name
with the values you choose:$ ansible-galaxy collection init <my_namespace>.<my_collection_name>
NoteMake 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:
-
A file
meta/execution-environment.yml
references the Python and/orbindep
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.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 awx-manage
command.
Procedure
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 awx-manage
command.
Procedure
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.
Procedure
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
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. Execute 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.
Prerequisites
- A playbook.
-
A valid inventory file if not using
localhost
or an inventory plugin.
Procedure
Start Automation content navigator
$ ansible-navigator
Run the playbook. You can optionally type
ansible-navigator run simple-playbook.yml -i inventory.yml
to directly run the playbook.$ :run
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
Tab to
Submit
and 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.Optionally, type
:doc
bring 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 ...>
Additional resources
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.
Prerequisites
- A Automation content navigator artifact JSON file from a playbook run.
Procedure
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.
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.