Red Hat Enterprise Linux Automation with Ansible
Select and retrieve roles from external sources such as Git repositories or Ansible Galaxy, and use them in your playbooks.
If you are using roles in your Ansible Playbooks, then you should get those roles from some centrally managed source. This practice ensures that all your projects have the current version of the role and that each project can benefit from bug fixes discovered by other projects with which they share the role.
For example, if the role is private content created and curated by your organization, it might be stored in a Git repository managed by your organization.
Alternatively, it might be distributed as a tar archive file from a website or through other means.
In addition, the open source community maintains some roles through the Ansible Galaxy website. These roles are not reviewed or supported officially by Red Hat, but might contain code that your organization finds useful.
Important
It is increasingly common for roles to be packaged as Ansible Content Collections and offered by their authors through various methods:
In Red Hat Certified Ansible Content Collections from the Red Hat hosted 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 Collections.
Ideally, you want to be able to download the latest version of the role into the roles directory of your project simply, whenever necessary.
A public library of Ansible content written by a variety of Ansible administrators and users is available at https://galaxy.ansible.com[Ansible Galaxy]. This 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.
The ansible-galaxy command that you use to download and manage roles from Ansible Galaxy can also be used to download and manage roles from your own Git repositories.
The ansible-galaxy command-line tool can be used to search for, display information about, install, list, remove, or initialize roles.
If you have a playbook that must have specific roles installed, then you can create a roles/requirements.yml file in the project directory that specifies which roles are needed.
This file acts as a dependency manifest for the playbook project that enables playbooks to be developed and tested separately from any supporting roles.
Then, before you run ansible-navigator run, you can use the ansible-galaxy command to install those roles in your project's roles directory.
Note
If you use automation controller, it automatically downloads roles specified in your roles/requirements.yml file when it runs your playbook.
For example, you could have a role in a public repository on a Git server at https://git.example.com/someuser/someuser.myrole.
A simple requirements.yml to install someuser.myrole might contain the following content:
- src: https://git.example.com/someuser/someuser.myrole scm: git version: "1.5.0"
The src attribute specifies the source of the role, in this case the URL for the repository of the role on your Git server.
You can also use SSH key-based authentication by specifying something like git@git.example.com:someuser/someuser.myrole 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.
In the case of a role stored in Git, 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, you get the latest version of the role.
If the upstream author makes changes to the role that are incompatible with your playbook, it might cause an automation failure or other problems.
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
[user@host project]$ansible-galaxy role install -r roles/requirements.yml \>-p rolesStarting galaxy role install process - downloading role from https://git.example.com/someuser/someuser.myrole - extracting myrole to /home/user/project/roles/someuser.myrole - someuser.myrole (1.5.0) was installed successfully
Important
If you do not specify the -p roles option, then ansible-galaxy uses the first directory in the default roles_path setting 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 ansible-navigator 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:
roles_path = roles
If you have a tar archive file that contains a role, you can use roles/requirements.yml to install that file from a URL:
# from a role tar ball, given a URL; # supports 'http', 'https', or 'file' protocols - src: file:///opt/local/roles/tarrole.tar name: tarrole - src: https://www.example.com/role-archive/someuser.otherrole.tar name: someuser.otherrole
Note
Red Hat recommends that you use version control with roles, storing them in a version control system such as Git. If a recent change to a role causes problems, using version control allows you to roll back to a previous, stable version of the role.
The open source Ansible community operates a public server, https://galaxy.ansible.com, that contains roles and Ansible Content Collections shared by other Ansible users.
Warning
These roles 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.
The tab on the left side of the Ansible Galaxy website home page gives you access to information about the roles published on Ansible Galaxy. You can search for an Ansible role by name or by using tags or other role attributes.
Results are presented in descending order of the Best Match score, which is a computed score based on role quality, role popularity, and search criteria.
(Content Scoring in the Ansible Galaxy documentation has more information on how roles are scored by Ansible Galaxy.)
Ansible Galaxy reports the number of times each role has been downloaded from Ansible Galaxy. In addition, Ansible Galaxy also reports the number of watchers, forks, and stars the role's GitHub repository has. You can use this information to help determine how active development is for a role and how popular it is in the community.
The following figure shows the search results that Ansible Galaxy displayed after a keyword search for redis was performed.
The menu to the right of the search box allows searches by type, contributor type, contributor, cloud platform, deprecated, platform, and tags.
Possible platform values include EL for Red Hat Enterprise Linux (and closely related distributions such as CentOS) and Fedora, among others.
Tags are arbitrary single-word strings set by the role author that describe and categorize the role.
You can use tags to find relevant roles.
Possible tag values include system, development, web, monitoring, and others.
In Ansible Galaxy, a role can have up to 20 tags.
Important
In the Ansible Galaxy search interface, keyword searches match words or phrases in the README file, content name, or content description.
Tag searches, by contrast, specifically match tag values that the author set for the role.
The ansible-galaxy search subcommand searches Ansible Galaxy for roles.
If you specify a string as an argument, it is used to search Ansible Galaxy for roles by keyword.
You can use the --author, --platforms, and --galaxy-tags options to narrow the search results.
You can also use those options as the main search key.
For example, the command ansible-galaxy search --author geerlingguy displays all roles submitted by the user geerlingguy.
Results are displayed in alphabetical order, not by descending Best Match score.
The following example displays the names of roles that include redis, and are available for the Enterprise Linux (EL) platform.
[user@host ~]$ ansible-galaxy search 'redis' --platforms EL
Found 251 roles matching your search:
Name Description
---- -----------
0x0i.consul Consul - a service discovery, mesh and confi>
0x0i.grafana Grafana - an analytics and monitoring observ>
0x5a17ed.ansible_role_netbox Installs and configures NetBox, a DCIM suite>
1it.sudo Ansible role for managing sudoers
adfinis-sygroup.redis Ansible role for Redis
AerisCloud.librato Install and configure the Librato Agent
AerisCloud.redis Installs redis on a server
AlbanAndrieu.java Manage Java installation
alikins.php_pecl PHP PECL extension installation.
...output omitted...The ansible-galaxy info subcommand displays more detailed information about a role.
Ansible Galaxy gets this information from a number of places, including the role's meta/main.yml file and its GitHub repository.
The following command displays information about the geerlingguy.redis role, available from Ansible Galaxy.
[user@host ~]$ ansible-galaxy info geerlingguy.redis
Role: geerlingguy.redis
description: Redis for Linux
active: True
...output omitted...
download_count: 825486
forks_count: 137
github_branch: master
github_repo: ansible-role-redis
github_user: geerlingguy
...output omitted...
license: license (BSD, MIT)
min_ansible_version: 2.4
modified: 2020-11-17T19:20:46.649130Z
open_issues_count: 5
path: ('/home/student/.ansible/roles', '/usr/share/ansible/roles', '/etc/ansible/role>
role_type: ANS
stargazers_count: 170
...output omitted...The following example shows how to configure a requirements file that uses a variety of remote sources.
[user@host project]$cat roles/requirements.yml# from Ansible Galaxy, using the latest version - src: geerlingguy.redis# from Ansible Galaxy, overriding the name and using a specific version - src: geerlingguy.redis version: "1.5.0"
name: redis_prod # from any Git based repository, using HTTPS - src: https://github.com/geerlingguy/ansible-role-nginx.git scm: git
version: master name: nginx # from a role tar ball, 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 tar archive, the |
| 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
- geerlingguy.redis, 1.7.0
- redis_prod, 1.5.0
- nginx, master
- myrole, (unknown version)
...output omitted...You can remove a role with the ansible-galaxy remove subcommand.
[user@host ~]$ ansible-galaxy remove nginx
- successfully removed nginx
