Technical resources
Testing content Collections with Ansible Automation Platform 2.0
Introduction and Recap
Execution environments are supported by two new tools that are built on top of Ansible content Collections: Automation content navigator (ansible-navigator) and automation execution environment builder (ansible-builder).
Content Collections now support dependency addition in the form of requirements.txt, a file containing Python dependencies, as well as bindep.txt, a file containing RPM packaging dependencies. Both tools can take advantage of those files being present in your Collections to build execution environments and then subsequently test those execution environments built with your Collections.
Why does testing matter?
As a technology partner, you probably already currently develop and maintain, or are in the process of developing a certified Ansible content Collection for your solution or product. With the new early access release of Ansible Automation Platform 2.0, we have introduced new tools that will help automation content developers focus more on creating actual automation instead of the tedious but important platform operational environments.
This also means that as a certified Red Hat technology partner, additional testing policies and procedures ensure that your content Collections work as expected with the new tooling, to provide an expected user experience of your Collections with Ansible Automation Platform.
What is an execution environment?
Having consistent, reliable automation is key to a successful IT strategy. One Red Hat Ansible Automation Platform customer had their internal administration team having to maintain over 40 different Python virtual environments across many different teams. Some used different versions of Ansible, some required different automation content (and dependencies) for their specific devices, and some started building their own environments for testing.
With no platform tools for supporting and maintaining these specific python virtual environments, custom environments continue to proliferate, drift happens between development and production, and the cost and complexity of automation increases. Furthermore, this burden is on the platform administrator to keep track of all while ensuring the automation platform is operational.
To solve for all this, Ansible Automation Platform 2 introduces a new construct called automation execution environments. These are immutable images on which all automation is run. Each automation execution environment contains the following:
- RHEL UBI 8
- Ansible 2.9 or Ansible Core 2.11
- Python 3.8
- Any content Collections
- Collection Python or binary dependencies
This provides a standardized way to define, build and distribute the environments that the automation runs in. In a nutshell, automation execution environments are packaged as container images that allow for easier administration of Ansible between the Ansible developer and the Ansible platform administrator.
Getting access to Execution Environments
With the release of Ansible Automation Platform 2, there are a set of three prebuilt and supported execution environments available on the Red Hat Ecosystem Catalog (was: Red Hat Container Registry). These images can be used in different capacities in your organization’s environment and are provided as part of the Ansible Automation Platform subscription.
- Minimal (ee-minimal-rhel8) - Contains Ansible 2.11 with UBI8 and Python 3.8. This image does not contain any content Collections. You can use this image as the base image to build additional execution environments with your custom Collections or with any of the certified Collections available on Automation Hub.
- Supported (ee-supported-rhel8) - This is the default image available with automation controller. It contains the same contents as the minimal execution environment but also contains all content Collections built and supported by Red Hat.
- Compatibility (ee-29-rhel8) - Contains Ansible 2.9 with UBI8 and Python 3.8. This image is best for customers who are planning to migrate to Ansible Automation Platform 2 from an earlier version such as Ansible Automation Platform 1.2.
Please note that the automation execution environment builder (ansible-builder) is used to build custom execution environments by layering on top of the images provided with Ansible Automation Platform 2.0. Please refer to the following resources for more information on how to build your own execution environment on top of the default ones provided by Ansible Automation Platform:
- Ansible Automation Platform 2 launch blog featuring execution environments
- Self-paced on-demand interactive lab for ansible-builder
- Introduction to Ansible Builder
- Customizing an Existing Execution Environment Image section of the ansible-builder documentation Building Execution Environments with Collections using Ansible Builder
As a partner, you might want to provide customers with the execution environment which has your Collections built-in. Furthermore, customers might be putting your Collections in their own custom execution environments.
Please refer to the Github repository we have created specifically to help technology partners create an execution environment with your own Collections on top of the minimal execution environment.
** Note: Your collection dependencies will be automatically pulled as part of the build process if the requirements.txt and bindep.txt files (if required) are filled in your published collection on Automation Hub.
If you are using the supplied ansible-builder RPM with Ansible Automation Platform 2.0 early access release, you don’t need to specify the base and builder images as mentioned in the following example.
Leveraging automation content navigator
Automation content navigator (ansible-navigator) is a textual user interface (TUI) as well as a command line interface (CLI) for the Ansible Automation Platform. As a partner, you can use automation content navigator to test the Ansible Automation Platform 2 customer workflows.
Automation content navigator can run playbooks directly with a referenced execution environment. The goal for automation content navigator is to provide a standard way to port Ansible user environments easily from development to production without the hassle of managing Python virtual environments and Ansible module dependencies across various environments.
Getting started:
- Ansible Automation Platform 2.0 launch blog featuring automation content navigator
- Check out the automation content navigator upstream project
- Self-paced on-demand interactive lab for ansible-navigator
- Test if your playbooks are working properly with your execution environments with a basic setup explained
- Refer to this sample repo as an example to set up the automation content navigator workflow
pip install ansible-navigator
|
**NOTE** The project installed via pip can be replaced with Ansible Automation Platform 2.0 which is now available to customers and partners via early access on the Red Hat Customer Portal. Also, please check the automation content navigator documentation.
Once you clone the repo locally, the demo will explain how to change it to run a playbook that uses modules from your Collections from inside the execution environment you've created.
If you check the repo structure, at the top level you can find the configuration file ansible-navigator.yml is found at the top level. This file is used as a configuration file for ansible-navigator and you can use it to point to the execution environment with your Collection, created in earlier steps. You can also find out more about the settings precedence if applicable.
Please check the line:
https://github.com/anshulbehl/ntp_demo/blob/main/ansible-navigator.yml#L15
Change the image name on the line to the execution environment created in earlier steps
image: <name_of_your_execution_environment>
|
Once that is done, please run the below command to see if your collection shows up in the list of Collections discovered by ansible-navigator.
ansible-navigator collections
|
The output should be similar to this example output:
NAME VERSION SHADOWED TYPE PATH 0│ansible.netcommon 2.0.2 False contained /usr/share/ansible/collections/ansible_collections/ansible/netcommon/1│ansible.utils 1│ansible.utils 2.1.0 False contained /usr/share/ansible/collections/ansible_collections/ansible/utils/ 2│partner.collection version False contained /usr/share/ansible/collections/ansible_collections/partner/collection/
ansible-navigator run -m interactive sample_playbook.yml -i sample_inventory.yaml
|
Note: The default container runtime is podman inside the ansible-navigator settings.
Next Steps
Once you have completed the above steps without any issues, you can feel confident that your collection will be ready and prepared to run with Ansible Automation Platform 2.0
With the release of Red Hat Ansible Automation Platform 2 certification policy for the content Collections has changed to testing against Ansible Core 2.11, which is the included Ansible Core version in minimal and supported execution environments. Please test your Collection with execution environments with the process explained above to make sure it can be certified with the new version of Red Hat Ansible Automation Platform.
Once you have tested your content Collections with Ansible Core 2.11 our recommendation is to update all the relative documentation as well as using the README files to explicitly state what versions of Ansible Core you support following the format. Refer to the following:
Ansible version compatibility
This collection has been tested against the following Ansible versions: >=2.9, 2.11.
Automation Hub has a feature planned to use the UI to state which versions the collection is certified against (see the lead up to that feature below). Until then, the documentation will be the main venue for customers to understand for which version your content is currently certified.
As always, if you have any questions or issues with certifying, please don’t hesitate to reach out to us at ansiblepartners@redhat.com.
