This topic describes how to download and install Ansible content from Galaxy.
$ ansible-galaxy install debops.apt
When Ansible is first installed, it defaults to installing content in /etc/ansible/roles, which requires root privileges.
The first way to override the deault behavior is to use the –roles-path option on the command line, as demonstrated by the following example:
$ ansible-galaxy install --roles-path ~/ansible-roles debops.apt
Override the default behavior by setting the environment variable
ANSIBLE_ROLES_PATH. When set, the
ANSIBLE_ROLES_PATH variable is used during playbook execution to locate installed roles, and by
to determine where to install roles. It can be set to a single directory path, or to a list of paths
(e.g., /etc/ansible/roles:~/.ansible/roles). If set to a list,
ansible-galaxy will install roles to
the first writable path.
Ansible also supports a configuration file,
roles_path can be set. Setting the value of
roles_path behaves the same as setting the
ANSIBLE_ROLES_PATH environment variable.
When the Galaxy server imports a role, it imports any git tags matching the Semantic Version format as versions. In turn, a specific version of a role can be downloaded by specifying one of the imported tags.
To see the available versions, locate the role on the search page, and click on the name to view more details. You can also navigate directly to the role using the /<namespace>/<role name>. For example, to view the role geerlingguy.apache, go to https://galaxy.ansible.com/geerlingguy/apache.
For multi-role repositories, now supported in Galaxy v3.0+, the direct path to an individual role contained in the repository is /<namespace>/<repository_name>/<role_name>.
Install a specific version of a role by appending a comma and a version tag. For example, the following installs v1.0.0 of the role.
$ ansible-galaxy install geerlingguy.apache,v1.0.0
It’s also possible to point directly to the git repository and specify a branch name or commit hash as the version. For example, the following installs a specific commit:
$ ansible-galaxy install git+https://github.com/geerlingguy/ansible-role-apache.git,0b7cd353c0250e87a26e0499e59e7fd265cc2f25
Multiple roles can be installed by listing them in a requirements.yml file. The format of the file is YAML, and the file extension must be either .yml or .yaml.
Use the following command to install roles included in requirements.yml:
$ ansible-galaxy install -r requirements.yml
Each role in the file will have one or more of the following attributes:
- The source of the role, and a required attribute. Specify a role from Galaxy by using the format namespace.role_name, or provide a URL to a repository within a git based SCM.
- If the src is a URL, specify the SCM. Only git or hg are supported. Defaults to git.
- The version of the role to download. Provide a tag value, commit hash, or branch name. Defaults to master.
- Download the role to a specific name. Defaults to the Galaxy name when downloading from Galaxy, or the name of the repository, when src is a URL.
The following example provides a guide for listing roles in a requirements.yml file:
# from galaxy - src: yatesr.timezone # from GitHub - src: https://github.com/bennojoy/nginx # from GitHub, overriding the name and specifying a specific tag - src: https://github.com/bennojoy/nginx version: master name: nginx_role # from a webserver, where the role is packaged in a tar.gz - src: https://some.webserver.example.com/files/master.tar.gz name: http-role # from Bitbucket - src: git+http://bitbucket.org/willthames/git-ansible-galaxy version: v1.4 # from Bitbucket, alternative syntax and caveats - src: http://bitbucket.org/willthames/hg-ansible-galaxy scm: hg # from GitLab or other git-based scm - src: email@example.com:mygroup/ansible-base.git scm: git version: "0.1" # quoted, so YAML doesn't parse this as a floating-point value
Using the include directive, additional YAML files can be included into a single requirements.yml file. For large projects, this provides the ability to split a large file into multiple smaller files.
For example, a project may have a requirements.yml file, and a webserver.yml file. The following shows the contents of the requirements.yml file:
# from galaxy - src: yatesr.timezone - include: <path_to_requirements>/webserver.yml
Below are the contents of the webserver.yml file:
# from github - src: https://github.com/bennojoy/nginx # from Bitbucket - src: git+http://bitbucket.org/willthames/git-ansible-galaxy version: v1.4
To install all the roles from both files, pass the root file, in this case requirements.yml on the command line, as demonstrated by the following:
$ ansible-galaxy install -r requirements.yml
Roles can be dependent on roles, and when a role is installed, any dependencies are automatically installed as well.
Dependencies are listed in a role’s
meta/main.yml file, using the top-level dependencies keyword.
The following shows an example
meta/main.yml file with dependent roles:
--- dependencies: - geerlingguy.java galaxy_info: author: geerlingguy description: Elasticsearch for Linux. company: "Midwestern Mac, LLC" license: "license (BSD, MIT)" min_ansible_version: 2.4 platforms: - name: EL versions: - all - name: Debian versions: - all - name: Ubuntu versions: - all galaxy_tags: - web - system - monitoring - logging - lucene - elk - elasticsearch
If the source of a role is Galaxy, specify the role in the format namespace.role_name, as shown in the above example. The more complex format used in requirements.yml is also supported, as deomonstrated by the following:
dependencies: - src: geerlingguy.ansible - src: git+https://github.com/geerlingguy/ansible-role-composer.git version: 775396299f2da1f519f0d8885022ca2d6ee80ee8 name: composer
To understand how dependencies are handled during playbook execution, view the Role Dependencies topic at the Ansible doc site.
Galaxy expects all role dependencies to exist in Galaxy, and therefore dependencies to be specified using the namespace.role_name format.
Traditionally, a role is a git repository. Galaxy v3.0 introduced multi-role repositories, providing the ability to combine multiple roles into a single git repository.
Installing a mult-role repository requires using the
mazer command line tool available at the Ansible
This is a tech-preview feature. Future releases of Galaxy may change or break support of multi-role repositories.
All the roles from a multi-role repository can be installed using mazer’s
install command, and passing the
namespace.repository_name, as demonstrated by the following command:
$ mazer install testing.multi_role_repository
For more on installing, configuring, and using Mazer, visit the Ansible Mazer project