The ansible-galaxy command line tool can be used to search for, display information about, install, list, remove, or initialize roles.
Searching for Roles from the Command Line
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 will display 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 124 roles matching your search: Name Description ---- ------------ 1it.sudo Ansible role for managing sudoers AerisCloud.librato Install and configure the Librato Agent AerisCloud.redis Installs redis on a server AlbanAndrieu.java Manage Java installation andrewrothstein.redis builds Redis from src and installs ...output omitted... geerlingguy.php-redis PhpRedis support for Linux geerlingguy.redis Redis for Linux gikoluo.filebeat Filebeat for Linux.
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: 146209 forks_count: 82 github_branch: master github_repo: ansible-role-redis github_user: geerlingguy ...output omitted... license: license (BSD, MIT) min_ansible_version: 2.4 modified: 2018-11-19T14:53:29.722718Z open_issues_count: 11 path: [u'/etc/ansible/roles', u'/usr/share/ansible/roles'] role_type: ANS stargazers_count: 98
Installing Roles from Ansible Galaxy
The ansible-galaxy install subcommand downloads a role from Ansible Galaxy, then installs it locally on the control node. By default, roles are installed into the first directory that is writable in the user’s roles_path. Based on the default roles_path set for Ansible, normally the role will be installed into the user’s ~/.ansible/roles directory. The default roles_path might be overridden by your current Ansible configuration file or by the environment variable ANSIBLE_ROLES_PATH, which affects the behavior of ansible-galaxy.
You can also specify a specific directory to install the role into by using the -p DIRECTORY option. In the following example, ansible-galaxy installs the geerlingguy.redis role into a playbook project’s roles directory. The command’s current working directory is /opt/project.
[user@host project]$ ansible-galaxy install geerlingguy.redis -p roles/ - downloading role 'redis', owned by geerlingguy - downloading role from https://github.com/geerlingguy/...output omitted... - extracting geerlingguy.redis to /opt/project/roles/geerlingguy.redis - geerlingguy.redis (1.6.0) was installed successfully [user@host project]$ ls roles/ geerlingguy.redis
Installing Roles Using a Requirements File
You can also use ansible-galaxy to install a list of roles based on definitions in a text file. For example, if you have a playbook that needs to have specific roles installed, 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 which enables playbooks to be developed and tested separately from any supporting roles.
For example, a simple requirements.yml to install geerlingguy.redis might read like this:
- src: geerlingguy.redis version: "1.5.0"
The src attribute specifies the source of the role, in this case the geerlingguy.redis role from Ansible Galaxy. The version attribute is optional, and specifies the version of the role to install, in this case 1.5.0.
To install the roles using a role file, use the -r REQUIREMENTS-FILE option:
[user@host project]$ ansible-galaxy install -r roles/requirements.yml -p roles - downloading role 'redis', owned by geerlingguy - downloading role from https://github.com/geerlingguy/ansible-role-redis/archive/1.6.0.tar.gz - extracting geerlingguy.redis to /opt/project/roles/geerlingguy.redis - geerlingguy.redis (1.6.0) was installed successfully
You can use ansible-galaxy to install roles that are not in Ansible Galaxy. You can host your own proprietary or internal roles in a private Git repository or on a web server. The following example shows how to configure a requirements file using 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://gitlab.com/guardianproject-ops/ansible-nginx-acme.git scm: git version: 56e00a54 name: nginx-acme # from any Git-based repository, using SSH - src: email@example.com:guardianproject-ops/ansible-nginx-acme.git scm: git version: master name: nginx-acme-ssh # from a role tar ball, given a URL; # supports 'http', 'https', or 'file' protocols - src: file:///opt/local/roles/myrole.tar name: myrole
The src keyword specifies the Ansible Galaxy role name. If the role is not hosted on Ansible Galaxy, the src keyword indicates the role’s URL. If the role is hosted in a source control repository, the scm attribute is required. The ansible- galaxy command is capable of downloading and installing roles from either a Git-based or mercurial-based software repository. A Git-based repository requires an scm value of git, while a role hosted on a mercurial repository requires a value of hg. If the role is hosted on Ansible Galaxy or as a tar archive on a web server, the scm keyword is omitted.
The name keyword is used to override the local name of the role. The version keyword is used to specify a role’s version. The version keyword can be any value that corresponds to a branch, tag, or commit hash from the role’s software repository. To install the roles associated with a playbook project, execute the ansible-galaxy install command:
[user@host project]$ ansible-galaxy install -r roles/requirements.yml -p roles - downloading role 'redis', owned by geerlingguy - downloading role from https://github.com/geerlingguy/ansible-role-redis/archive/1.6.0.tar.gz - extracting geerlingguy.redis to /opt/project/roles/geerlingguy.redis - geerlingguy.redis (1.6.0) was installed successfully - downloading role 'redis', owned by geerlingguy - downloading role from https://github.com/geerlingguy/ansible-role-redis/archive/1.5.0.tar.gz - extracting redis_prod to /opt/project/roles/redis_prod - redis_prod (1.5.0) was installed successfully - extracting nginx-acme to /opt/project/roles/nginx-acme - nginx-acme (56e00a54) was installed successfully - extracting nginx-acme-ssh to /opt/project/roles/nginx-acme-ssh - nginx-acme-ssh (master) was installed successfully - downloading role from file:///opt/local/roles/myrole.tar - extracting myrole to /opt/project/roles/myrole - myrole was installed successfully
Managing Downloaded Roles
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 roles that are found locally.
[user@host project]$ ansible-galaxy list - geerlingguy.redis, 1.6.0 - myrole, (unknown version) - nginx-acme, 56e00a54 - nginx-acme-ssh, master - redis_prod, 1.5.0
A role can be removed locally with the ansible-galaxy remove subcommand.
[user@host ~]$ ansible-galaxy remove nginx-acme-ssh - successfully removed nginx-acme-ssh
[user@host ~]$ ansible-galaxy list - geerlingguy.redis, 1.6.0 - myrole, (unknown version) - nginx-acme, 56e00a54 - redis_prod, 1.5.0
Use downloaded and installed roles in playbooks like any other role. They may be referenced in the roles section using their downloaded role name. If a role is not in the project’s roles directory, the roles_path will be checked to see if the role is installed in one of those directories, first match being used. The following use-role.yml playbook references the redis_prod and geerlingguy.redis roles:
[user@host project]$ cat use-role.yml --- - name: use redis_prod for Prod machines hosts: redis_prod_servers remote_user: devops become: true roles: - redis_prod - name: use geerlingguy.redis for Dev machines hosts: redis_dev_servers remote_user: devops become: true roles: - geerlingguy.redis
This playbook causes different versions of the geerlingguy.redis role to be applied to the production and development servers. In this manner, changes to the role can be systematically tested and integrated before deployment to the production servers. If a recent change to a role causes problems, using version control to develop the role allows you to roll back to a previous, stable version of the role.