Updated April 4, 2023
Introduction to Ansible Galaxy
Ansible Galaxy is a web-based online and open-source repository for sharing and finding Ansible content mostly roles and collections. It is as if we have created something new and wanted to share with others, upload it to Ansible Galaxy or if we have any issues related to Ansible automation or want a pre-packaged solution provided by others to quickly jump-start our automation projects, we can find it on Ansible Galaxy. It might be roles, modules, plugins, or collections. There are already many community authors who have uploaded their Ansible roles, collections, etc.
We use ‘ansible-galaxy’ command to accomplish tasks like installation of roles from Galaxy or any git SCM, creating new roles, removing roles, or performing tasks on the Galaxy website. This command is already bundled with Ansible so we can use it right after installing Ansible. Galaxy project is an open-source project so we can host our internal Galaxy server. To use the internal Galaxy server, we need to override the default configuration in our ansible.cfg file with server address of our Galaxy internal server as by default, it uses server address https://galaxy.ansible.com.
How to work with Roles or Collections in Ansible Galaxy?
Let us study some roles:
1. Roles
We use ‘ansible-galaxy’ command to install the roles from the Galaxy server as below:
Code:
ansible-galaxy install <role_name>
Output:
ansible-galaxy install singleplatform-eng.users
Explanation: In the above example, it downloads the ‘users’ role, owned by single platform-eng, and installs it. ‘ansible-galaxy’ command installs roles to the default directory that is ‘/etc/ansible/roles’ however if we want to install roles to a specific directory, we can do it by using one of the three methods.
The first one is to use –roles-path option while installing the roles as below:
Code:
ansible-galaxy install --roles-path <directory_path><role_name>
Output:
ansible-galaxy install --roles-path /ansible-roles singleplatform-eng.users
Explanation: – In the above example, it installs the role in /ansible-roles directory. If the directory does not exist then it will be created by the command itself. We can install the same role multiple times with different paths each time.
The second one is to set the environment variable ‘ANSIBLE_ROLES_PATH’. We can seta a single directory path or list of paths however it installs roles to the first writable path.
Code:
export ANSIBLE_ROLES_PATH=/anisble-roles
ansible-galaxy install singleplatform-eng.users
Output:
The third one is to set ‘roles_path’ in the ansible.cfg configuration file.
ansible-galaxy install single platform-eng.users
Explanation: – In the above command, it installs the role to the directory defined in the configuration file, however, if the environment variable is also defined then it will take precedence.
If there is a requirement to install a specific version of any role, we can do so by using a comma after the role name as below:
Code:
ansible-galaxy install <role_name>,<role_version>
Output:
ansible-galaxy install singleplatform-eng.users,v1.2.5
Explanation: – In the above example, it downloads v1.2.5 as specified in the command. If roles already exist with a different version, use –force command to change the version or remove the old role before installing a different version of the role.
We can list the installed roles using ‘list’ command as below:
Code:
ansible-galaxy list
Output:
Explanation: – In the above example, it shows installed roles in the directory /ansible-roles that is defined in the environment variable, roles-path rules will apply in the same way to list the roles, we can even use –roles-path option to display the roles installed in a specific directory.
We can install multiple roles from a single YAML file. We can define one or more attributes like src, SCM, version, name, etc.
Code:
cat role_file.yaml
#from galaxy
-src: singleplatform-eng.users
Output:
ansible-galaxy install -r role_file.yaml
Explanation: – In the above example, we define only src and give the name of the role so it will check in the galaxy and install the roles if available. We can install roles from other sources like GitHub, Bitbucket, etc. and specify other attributes as well like version, name, etc.
We can create our roles using init command as below:
Code:
ansible-galaxy init <role_name>
Output:
ansible-galaxy init my_role
Explanation: – In the above example, it creates a role named ‘my_role’. It creates a folder structure for our roles.
There are the essential commands that we discussed above however there are other operations we can perform on roles. We can use ‘–help’ command as below to know more about it:
Code:
ansible-galaxy role --help
Output:
2. Collections
We can install a collection from Galaxy as below if the internal server is not defined in the configuration file.
Code:
ansible-galaxy collection install <collection_name>
Output:
ansible-galaxy collection install newswangerd.collection_demo
We can also install a specific version of a collection using ‘:==’ as below:
Code:
ansible-galaxy collection install <collection_name>:==<version>
Output:
ansible-galaxy collection installnewswangerd.collection_demo:==1.0.6
Explanation: – In the above example, it installs version 1.0.6 of a collection called newswangerd.collection_demo. We need to specify –force option to override the collection if already exists.
We can even specify a range to install the most recent version within that range. For detailed information please check official documents. We can install collections using the YAML file as well and specify directives like name, version, source, etc. as we do it for roles.
Code:
---
collections:
#with collection name and version options
- name: alikins.collection_inspect
version: ‘>0.0.9,<1.0.0’
Output:
Explanation: – In the above example, it uses a YAML file to install collection and we have specified the range in version directives. As per our range, it will install the most recent version that is greater than ‘0.0.9’ and less than ‘1.0.0’. If we check on the Galaxy website, it has only one version ‘0.0.49’ that falls in our range so it installs that version.
We can create our collection in the same way we create roles as below: –
Code:
ansible-galaxy collection init my_namespace.my_collection
Output:
If we have any doubt in any command, we can use ‘–help’ or ‘-h’ as below to know more about the commands:
Code:
ansible-galaxy collection -h
Output:
How to Import Roles or Collection to the Ansible Galaxy
1. Go to galaxy.ansible.com and click on login as marked in below snapshot: –
2. We have to log in using our GitHub account so we must have an account on GitHub before login to Galaxy. We get the below page after clicking on the ‘Login’ button.
3. Once we clicked on above ‘Github’ icon, it redirects us to GitHub website to login and we get below page:
4. After entering the credential click on the ‘Sign in’ button and it takes us to the authorization page and once we authorize the GitHub account. It logged us into the ‘Ansible Galaxy’ website and we get additional options of ‘My Content’ and ‘My Imports’ in our left-hand side as highlighted in the below snapshot:
5. Once we clicked on the ‘My Content’ button, we got below page and to import our content, click on the ‘Add Content’ button as highlighted in the below snapshot:
6. We get the below page after clicking on the ‘Add Content’ button. We can ‘Import Role from GitHub’ or ‘Upload New Collection’ from our local computer.
7. Once we chose the role from GitHub or selected the file from our computer it validates the convention of the file if that is correct, we get the OK button to import it and we get the file under ‘My Imports’ tab as shown below:
Currently, it is showing as ‘No Imports’ because no file has been uploaded yet.
How to Search for Roles or Collection on ‘Ansible Galaxy’
1. We get below page once we browse to ‘galaxy.ansible.com’ or we can say below is the homepage of the ‘Ansible Galaxy’ website. We can click on any popular category from the homepage or click on the ‘Search’ button to get more filters to apply a granular search.
2. We enter a related keyword in ‘Search for…’ text and hit enter and to narrow the search result, click on filters button as highlighted in below snapshot:
3. We get filters like Type, Cloud Platform, Contributor, etc. after choosing the type we have another dropdown where we can choose the type like roles or collection and so on… We can also ascend or descend the output by ‘best match’, ‘Content Name’, ‘Download Count’, etc.
Conclusion
There are about 20K community authors on Ansible galaxy and about 24K roles and 281 collections available to kick start our automation project quickly. There is also Developer’s Guide for development workflow and Contributor Guide that go through the process of how one can contributor to the existing ‘Ansible Galaxy’ code as it is an open-source project. It is a centralized repository for finding and sharing Ansible roles and collections.
Recommended Articles
This is a guide to Ansible Galaxy. Here we discuss an introduction to Ansible Galaxy, how to work with roles and collections, how to import and how to search. You can also go through our other related articles to learn more –
