Network Automation with Red Hat Ansible Automation Platform
Select and retrieve roles from external sources such as Git repositories or Ansible Galaxy, and use them in your playbooks.
If you use roles in your Ansible Playbooks, then you might want to use a centrally managed location to store and manage them.
Using a centralized location for roles helps to ensure that your projects have the current version of the role, and that each project benefits from updates and bug fixes done by other project teams that share the role.
For example, if the role is created by your organization, that role might be stored in a Git repository managed by your organization, or as a .tar file.
The open source community maintains some roles through the Ansible Galaxy website at https://galaxy.ansible.com.
Ansible Galaxy is a public library of Ansible content written by various Ansible administrators and users, and is publicly available.
The Ansible Galaxy library contains thousands of Ansible roles, and it has a searchable database that helps you identify roles that might help you accomplish an administrative task.
Warning
The roles in the Ansible Galaxy library can be useful, but they are not supported by Red Hat, nor does Red Hat audit or review this code. Volunteers in the Ansible community maintain this site. Use these roles at your own risk.
You can search for roles on the https://galaxy.ansible.com website.
You can also use the ansible-galaxy search subcommand to search Ansible Galaxy for roles.
Use the --author, --platforms, and --galaxy-tags options to narrow the search results.
The following example displays the names of roles that include "vpn", and are available for the Enterprise Linux (EL) platform:
[user@host]$ ansible-galaxy search vpn --platforms EL
Found 70 roles matching your search:
Name Description
---- -----------
abelfodil.ansible_role_wireguard Installs Wireguard incl. systemd i
adamruzicka.wireguard Configure WireGuard VPN
ansyble.webtier Webtier deployment
aprt5pr.ocserv OpenConnect SSL VPN Server (ocserv)
arillso.wireguard Installation and configuration of
asm0dey.ansible_role_openvpn OpenVPN playbook for CentOS/Fedora
...output omitted...Use the ansible-galaxy command to download, install, and manage roles, whether they are from the Ansible Galaxy library or from some other source.
You can also use the ansible-galaxy command to search for, display information about, install, list, remove, or initialize roles.
By default, Ansible looks for installed roles in the following locations, ordered from the lowest to highest precedence:
In the same directory as your playbook
In the path specified by the
roles_pathvariableIn your project
rolesdirectory
Important
It is increasingly common for roles to be packaged as Ansible Content Collections and offered by their authors through the following methods:
In Red Hat Certified or Validated Ansible Content Collections from the Red Hat Ansible automation hub at
https://console.redhat.com, or through a private automation hubAs private content packaged from a private automation hub
By the community from Ansible Galaxy at
https://galaxy.ansible.com
This section only covers how to get roles that are not packaged into an Ansible Content Collection.
If your playbook requires that specific roles be installed, then you can create a roles/requirements.yml file in the project directory that specifies which roles are needed.
The roles/requirements.yml file acts as a dependency manifest for the playbook project that enables playbooks to be developed and tested separately from any supporting roles.
For example, you could have a role in a public repository on a Git server at https://git.example.com/someauthor/netrole.
A simple requirements.yml file to install the netrole role might contain the following content:
--- - src: https://git.example.com/someauthor/netrole scm: git version: "1.5.0"
The src attribute specifies the source of the role, in this case the location of the role repository on your Git server.
You can also use SSH key-based authentication by specifying something like git@git.example.com:someauthor/netrole as provided by your Git repository.
The scm attribute indicates that this role is from a Git repository.
The version attribute is optional, and specifies the version of the role to install, in this case 1.5.0.
If a role is stored in a Git repository, then the version can be the name of a branch, a tag, or a Git commit hash.
If you do not specify a version, the command uses the latest commit on the default branch.
Important
Specify the version of the role in your requirements.yml file, especially for playbooks in production.
If you do not specify a version, then you get the latest version available when you install the role.
If the upstream author makes changes to the role that are incompatible with your playbook, then the changes might cause an automation failure or other problems.
If you have a .tar file that contains a role, then you can use the roles/requirements.yml file to install that role.
--- # from a role .tar file, given a URL; # supports 'http', 'https', or 'file' protocols - src: file:///opt/local/roles/myrole.tar name: myrole - src: https://www.example.com/role-archive/someauthor.otherrole.tar name: someauthor.otherrole
Note
Red Hat recommends storing your roles in a version control system such as Git.
If a recent change to a role causes problems, then using version control enables you to roll back to a previous, stable version of the role.
To install roles using a role requirements file, run the ansible-galaxy role install command from within your project directory.
Include the following options:
-r roles/requirements.ymlto specify the location of your requirements file-p rolesto install the role into a subdirectory of therolesdirectory
Important
If you do not specify the -p roles option, then ansible-galaxy uses the first directory defined by the roles_path variable to determine where to install the role.
This defaults to the user's ~/.ansible/roles directory, which is outside the project directory and unavailable to the execution environment if you use the ansible-navigator command to run your playbooks.
One way to avoid the need to specify -p roles is to apply the following setting in the defaults section of your project's ansible.cfg file:
[defaults] roles_path = roles
[user@host project]$ansible-galaxy role install -r roles/requirements.yml \-p rolesStarting galaxy role install process - downloading role from https://git.example.com/someauthor/netrole - extracting netrole to /home/user/project/roles/netrole - netrole (1.5.0) was installed successfully
Important
If you use the ansible-navigator run command to run your playbook, then install all required roles before running the command.
If you use automation controller to run your playbook, then you do not need to manually install roles because automation controller automatically downloads all roles specified in your roles/requirements.yml file when it runs your playbook.
The following example shows how to configure a requirements file that uses various remote sources:
[user@host project]$cat roles/requirements.yml--- # from Ansible Galaxy, using the latest version - src: someauthor.netrole# from Ansible Galaxy, overriding the name and using a specific version - src: someauthor.netrole version: "1.5.0"
name: netrole # from any Git based repository, using HTTPS - src: https://github.com/someauthor/ansible-role-otherrole.git scm: git
version: main name: otherrole # from a role .tar file, given a URL; # supports 'http', 'https', or 'file' protocols - src: file:///opt/local/roles/myrole.tar
name: myrole
| The |
| The |
| If the role is hosted in a source control repository, the |
| If the role is hosted on Ansible Galaxy or as a |
| The |
The ansible-galaxy command can also manage local roles, such as those roles found in the roles directory of a playbook project.
The ansible-galaxy list subcommand lists the local roles.
[user@host project]$ ansible-galaxy list
# /home/user/project/roles
- netrole, 1.5.0
- otherrole, main
- myrole, (unknown version)
...output omitted...You can remove a role with the ansible-galaxy remove subcommand.
[user@host ~]$ ansible-galaxy remove myrole
- successfully removed myrole
