Red Hat Enterprise Linux Automation with Ansible
Obtain a set of related roles, supplementary modules, and other content from an Ansible Content Collection and use them in a playbook.
When Ansible was first developed, all the modules that it used were included as part of the core software package. As the number of modules increased, it became harder for the upstream project to manage all of these modules. Every module required a unique name and synchronizing module updates with updates to the core Ansible code.
With Ansible Content Collections, Ansible code updates are separated from updates to modules and plug-ins. An Ansible Content Collection provides a set of related modules, roles, and other plug-ins that you can use in your playbooks. This approach enables vendors and developers to maintain and distribute their collections at their own pace, independently of Ansible releases.
For example:
The
redhat.insightscontent collection provides modules and roles that you can use to register a system with Red Hat Insights for Red Hat Enterprise Linux.The
cisco.ioscontent collection, supported and maintained by Cisco, provides modules and plug-ins that manage Cisco IOS network appliances.The
community.cryptocontent collection provides modules that create SSL/TLS certificates.
Ansible Content Collections also provide flexibility. You can install only the content you need instead of installing all supported modules.
You can also select a specific version of a collection (possibly an earlier or later one) or choose between a version of a collection supported by Red Hat or vendors, or one provided by the community.
Ansible 2.9 and later support Ansible Content Collections. Upstream Ansible unbundled most modules from the core Ansible code in Ansible Base 2.10 and Ansible Core 2.11 and placed them in collections. Red Hat Ansible Automation Platform 2.2 provides automation execution environments based on Ansible Core 2.13 that inherit this feature.
Note
You can develop your own collections to provide custom roles and modules to your teams. Creating Ansible Content Collections of your own is outside the scope of this course. You can learn more about how to create Ansible Content Collections in the course that follows this one, Developing Advanced Automation with Red Hat Ansible Automation Platform (DO374).
To make it easier to specify collections and their contents by name, collection names are organized into namespaces. Vendors, partners, developers, and content creators can use namespaces to assign unique names to their collections without conflicting with other collections.
The namespace is the first part of a collection name.
For example, all the collections that the Ansible community maintains are in the community namespace, and have names like community.crypto, community.postgresql, and community.rabbitmq.
Likewise, Ansible Content Collections that Red Hat directly maintains and supports might use the redhat namespace, and have names like redhat.rhv, redhat.satellite, and redhat.insights.
Regardless of whether you are using ansible-navigator with the minimal automation execution environment or ansible-playbook on bare metal Ansible Core, you always have at least one Ansible Content Collection available to you: ansible.builtin.
In addition, your automation execution environment might have additional automation execution environments built into it, for example, the default execution environment used by Red Hat Ansible Automation Platform 2.2, ee-supported-rhel8.
If you need to have additional Ansible Content Collections, you can add them to the collections subdirectory of your Ansible project.
You might obtain Ansible Content Collections from several sources:
- Automation Hub
Automation hub is a service provided by Red Hat to distribute Red Hat Certified Ansible Content Collections that are supported by Red Hat and ecosystem partners. As an end customer, you can open a support ticket with Red Hat for these Ansible Content Collections that will be addressed by Red Hat and the ecosystem partner.
You need a valid Red Hat Ansible Automation Platform subscription to access automation hub. Use the automation hub web UI at https://console.redhat.com/ansible/automation-hub/ to browse these collections.
- Private Automation Hub
Your organization might have its own on-site private automation hub, and might also use that hub to distribute its own Ansible Content Collections. Private automation hub is included with Red Hat Ansible Automation Platform.
- Ansible Galaxy
Ansible Galaxy is a community-supported website that hosts Ansible Content Collections that have been submitted by a variety of Ansible developers and users. Ansible Galaxy is a public library that provides no formal support guarantees and that is not curated by Red Hat. For example, the
community.crypto,community.postgresql, andcommunity.rabbitmqcollections are all available from that platform.Use the Ansible Galaxy web UI at https://galaxy.ansible.com/ to search it for collections.
- Third-Party Git Repository or Archive File
You can also download Ansible Content Collections from a Git repository or a local or remote
tararchive file, much like you can download roles.
Before your playbooks can use content from an Ansible Content Collection, you must ensure that the collection is available in your automation execution environment.
The Ansible configuration collections_paths setting specifies a colon separated list of paths on the system where Ansible looks for installed collections.
You can set this directive in the ansible.cfg configuration file.
Important
The following default value references the collections_paths directive.
~/.ansible/collections:/usr/share/ansible/collections
If you set collections_paths to some other value in your Ansible project's ansible.cfg file and eliminate those two directories, then ansible-navigator cannot find the Ansible Content Collections provided inside the automation execution environment in its version of those directories.
The following example uses the ansible-galaxy collection install command to download and install the community.crypto Ansible Content Collection.
The -p collections option installs the collection in the local collections subdirectory.
[user@controlnode ~]$ansible-galaxy collection install community.crypto \>-p collections
Important
You must specify the -p collections option or ansible-galaxy installs the collection based on your current collections_paths setting, or into your ~/.ansible/collections/ directory on the control node by default.
The ansible-navigator command does not load this directory into the automation execution environment, although this directory is available to Ansible commands that use the control node as the execution environment, such as ansible-playbook.
When you install the community.crypto collection, you could see a warning that your Ansible project's playbooks might not find the collection because the specified path is not part of the configured Ansible collections path.
You can safely ingore this warning because your Ansible project checks the local collections subdirectory before checking directories specified by the collections_paths setting and can use the collections stored there.
The command can also install a collection from a local or a remote tar archive, or a Git repository.
A Git repository must have a valid galaxy.yml or MANIFEST.json file that provides metadata about the collection, such as its namespace and version number.
For example, see the community.general collection at https://github.com/ansible-collections/community.general.
[user@controlnode ~]$ansible-galaxy collection install \>/tmp/community-dns-1.2.0.tar.gz -p collections...output omitted... [user@controlnode ~]$ansible-galaxy collection install \>http://www.example.com/redhat-insights-1.0.5.tar.gz -p collections...output omitted... [user@controlnode ~]$ansible-galaxy collection install \>git@git.example.com:organization/repo_name.git -p collections
If your Ansible project needs additional Ansible Content Collections, you can create a collections/requirements.yml file in the project directory that lists all the collections that the project requires.
Automation controller detects this file and automatically installs the specified collections before running your playbooks.
A requirements file for Ansible Content Collections is a YAML file that consists of a collections dictionary key that has the list of collections to install as its value.
Each list item can also specify the particular version of the collection to install, as shown in the following example:
--- collections:- name: community.crypto
- name: ansible.posix version: 1.2.0
- name: /tmp/community-dns-1.2.0.tar.gz
- name: http://www.example.com/redhat-insights-1.0.5.tar.gz
- name: git+https://github.com/ansible-collections/community.general.git
version: main
| The value of this dictionary key is the list of collections that are required by the Ansible project. |
| Install the |
| Install version |
| Install an Ansible Content Collection from a particular local |
| Install an Ansible Content Collection from the |
| Install the |
The ansible-galaxy command can then use the collections/requirements.yml file to install all those collections.
Specify the requirements file with the --requirements-file (or -r) option, and use the -p collections option to install the Ansible Content Collection into the collections subdirectory.
[root@controlnode ~]#ansible-galaxy collection install \>-r collections/requirements.yml -p collections
By default, the ansible-galaxy command uses Ansible Galaxy at https://galaxy.ansible.com/ to download Ansible Content Collections.
You might not want to use this command, preferring automation hub or your own private automation hub.
Alternatively, you might want to try automation hub first, and then try Ansible Galaxy.
You can configure the sources that ansible-galaxy uses to get Ansible Content Collections in your Ansible project's ansible.cfg file.
The relevant parts of that file might look like the following example:
...output omitted... [galaxy] server_list = automation_hub, galaxy
| List all the repositories that the |
| Provide the URL to access the repository. |
| Provide the URL for authentication. |
| To access automation hub, you need an authentication token associated with your account.
Use the automation hub web UI at |
Instead of a token, you can use the username and password parameters to provide your customer portal username and password.
...output omitted... [galaxy_server.automation_hub] url=https://cloud.redhat.com/api/automation-hub/ username=operator1 password=Sup3r53cR3t ...output omitted...
However, you might not want to expose your credentials in the ansible.cfg file because the file could potentially get committed when using version control.
It is preferable to remove the authentication parameters from the ansible.cfg file and define them in environment variables, as shown in the following example:
export ANSIBLE_GALAXY_SERVER_<server_id>_<key>=value
-
server_id Server identifier in uppercase. The server identifier is the name you used in the
server_listparameter and in the name of the[galaxy_server.section.server_id]-
key Name of the parameter in uppercase.
The following example provides the token parameter as an environment variable:
[user@controlnode ~]$cat ansible.cfg...output omitted... [galaxy_server.automation_hub] url=https://cloud.redhat.com/api/automation-hub/ auth_url=https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token [user@controlnode ~]$export \>ANSIBLE_GALAXY_SERVER_AUTOMATION_HUB_TOKEN='eyJh...Jf0o'[user@controlnode ~]$ansible-galaxy collection install ansible.posix \>-p collections
After you install an Ansible Content Collection in your Ansible project, you can use it with that project's Ansible Playbooks.
You can use the ansible-navigator collections command in your Ansible project directory to list all the collections that are installed in your automation execution environment.
This includes the Ansible Content Collections in your project's collections subdirectory.
You can select the line number of the collection in the interactive mode of ansible-navigator to view its contents.
Then, you can select the line number of a module, role, or other plug-in to see its documentation.
You can also use other tools, such as ansible-navigator doc, with the FQCN of a module to view that module's documentation.
The following playbook invokes the mysql_user module from the community.mysql collection for a task.
---
- name: Create the operator1 user in the test database
hosts: db.example.com
tasks:
- name: Ensure the operator1 database user is defined
community.mysql.mysql_user:
name: operator1
password: Secret0451
priv: '.:ALL'
state: presentThe following playbook uses the organizations role from the redhat.satellite collection.
---
- name: Add the test organizations to Red Hat Satellite
hosts: localhost
tasks:
- name: Ensure the organizations exist
include_role:
name: redhat.satellite.organizations
vars:
satellite_server_url: https://sat.example.com
satellite_username: admin
satellite_password: Sup3r53cr3t
satellite_organizations:
- name: test1
label: tst1
state: present
description: Test organization 1
- name: test2
label: tst2
state: present
description: Test organization 2
