Updated April 13, 2023
Introduction to Ansible Collections
Ansible Collections are the format in which Ansible content like Modules, Roles, Playbooks and Plugin, etc. can be distributed to the Ansible users across Ansible community and Ansible users. An Ansible Collection can include a role, modules, playbook, plugins. This distribution is performed by Ansible Galaxy, which is a place from where you can install or get other developer’s shared content. Also, you can upload your code/content in Ansible Galaxy to further share it. There is a global location for the Ansible Galaxy server but if you have other Galaxy Server like RedHat Automation Hub, then you can configure the same in your Ansible setup.
Explaining Ansible Collections
Ansible Collections are collected from Ansible Galaxy the same way we import any roles. Only some syntax changes need to be noted while running the command for it and using any collection in playbooks.
So, below are some points which you must remember while working on Collections.
- To install a collection, you can use the below command. But note that we used -p here to specify the location of Ansible collection, this is set by COLLECTIONS_PATHSin Ansible configuration file and by default ~/.ansible/collections:/usr/share/ansible/collections.
ansible-galaxy collection install<collection_name> -p <collection_local_location>
- Along with default locations for collection, you can place your collection in the directory named as collections/ansible_collections/ adjacent to your playbook. This will follow the below directory structure.
my_playbook.yaml
├── collections/
│ └── ansible_collections/
│ └── our_Ansible_namespace/
│ └── our_Ansible_collection/< a playbook relevant collection's structure>
- Galaxy server by default will be used as https://galaxy.ansible.com, if you want to change it then you need to modify your working cfg file and list your Galaxy Servers under GALAXY_SERVER_LIST. Also, you can use –server in the command line to limit your collection’s search. In cases where you want to use your Ansible servers by default instead of global Ansible Galaxy location. You can modify ansible.cfg file and use a section named [galaxy]. Then place a list of collections after server_list.
Below is an example of such a section, where we have listed two Collections, one is RedHat Automation Hub and other is a sample, which can be prepared by us manually: –
[galaxy]
server_list = automation_hub, sample_galaxy_collection
[galaxy_server.automation_hub]
url=https://cloud.redhat.com/api/automation-hub/
auth_url=https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token
token=automation_hub_token
[galaxy_server.sample_galaxy_collection]
url=https://galaxy-dev.ansible.com/
token=sample_token
As you saw above there are certain parameters accepted by Ansible for an Ansible Collection.
Below is the list for same: –
- url: For the location of an Ansible Collection.
- token: This is mutually exclusive with the username. This is used to authenticate against a Galaxy Server.
- username: This is mutually exclusive with token and used for basic authentication with Galaxy Server.
- password: This is the password for the username above.
- auth_url: This is mutually exclusive with the username. auth_url requires a token. So this provides the location of the token endpoint
When installing any collection from Ansible Galaxy, by default the latest version will be installed. But if you need a specific version then you can use below operators to specify a version.
- :* For any version, this is default and will look for the latest.
- :!= For any version by not equal to specified ones.
- :== For a specified version.
- :>= For any version greater than equal to the one specified here.
- :> For any version greater than specified.
- :<= For any version lower than equal to the one specified here.
- :< For any version lower than specified.
Instead of installing on the command line, you can also set up a file like yaml, where you can give the list of collections that need to be installed under keyword collections. This can also work when you have defined your roles in the same file. A sample file will be like below: –
---
collections:
# Installing collection from Ansible_Galaxy.
- name: <namespace_name.collection_name>
source: https://galaxy.ansible.com
roles:
# Installing role from Ansible_Galaxy.
- name: <role_name>
If these cases where you have Ansible Roles and Collections defined in the same file for sake
of simplicity and consolidation. You can simply use the below command to install Collections only from this file.
ansible-galaxy collection install -r requirements.yml -p ./<file_location>
After installation, to use an Ansible collection inside a playbook, you shall refer it by using it FQCN (fully qualified collection name). This kind of reference works for modules, plugins as well as roles. Below is a code sample.
---
- hosts: all
collections:
- customized_namespace.customized_collection
tasks:
- import_role:
name: <role_name>
- my_module:
key: value
Similarly, there are few other alternatives.
How Ansible Collections Works?
In this section, we will see how we can use an Ansible Collection. We will download and install a collection from Ansible Galaxy and then use a module inside it to do something on the localhost. We will install a sample Ansible Collection named as newswangerd.collection_demo, which I just found on the Ansible galaxy website ( https://galaxy.ansible.com/), by searching.
We will install this Ansible collection using the below command, here we are not giving any path to the galaxy server, so by default, it will redirect to the global Ansible Galaxy server for source.
ansible-galaxy collection install newswangerd.collection_demo
In the output, we can see below, that the installation process started and created a directory structure under my workspace.
If we explore the directory structure created by this then we have below: –
tree .ansible/collections/ansible_collections/newswangerd/
Now using a module from this Ansible Collection can be done as below, we can see in the above picture that we have a module named as real_facts, which basically will print some lines on display: –
ansible localhost -m newswangerd.collection_demo.real_facts
Now, by running it, we will get an output like below: –
Please note that the above is just an example to show you how it works. You can browse Ansible Galaxy for a required Collection or you can develop one by yourself using Python Scripting.
Conclusion
As we saw in this article, the collection is a nice way to distribute content to your users or from Developers to Administrators. This helps to consolidate and streamline a similar or same type of playbook, roles, modules, and plugins. Adding this capability to your skillset makes you potent in Ansible. So, learn it first and then use it.
Recommended Articles
This is a guide to Ansible Collections. Here we discuss an introduction to Ansible Collections along with its working in detail explanation and examples. You may also have a look at the following articles to learn more –
