We have been covering some essential topics in Ansible and in this article, we will see yet another simple and important feature of Ansible called Collections.
What are Ansible Collections?
Ansible collections are a distribution format where you can bundle your ansible project and distribute it to others. A collection can include roles, plugins, modules, and playbooks. The collections should be hosted somewhere for anyone to pull down to their machine and use it.
Ansible galaxy is a popular distribution server where the ansible collections are hosted. Users can download the collection from ansible galaxy using the "
ansible-galaxy" command. There are alternatives to ansible-galaxy like ansible automation hub. You can also store the collections in version control systems like github, bitbucket and download from them too.
Ansible Galaxy Binary
To install collections, you need the "
ansible-galaxy" command installed on your machine. This command by default comes with your ansible installation. You can run the following command to verify if
ansible-galaxy command is installed:
$ which ansible-galaxy /home/ansuser/.local/bin/ansible-galaxy
To access the help section, you can run the following commands.
$ ansible-galaxy --help
ansible-galaxy command works for both collections and roles. If you need the list of helper options for collections, then run the following command.
$ ansible-galaxy collection --help
What is Galaxy Namespace?
When you sign-up with ansible-galaxy, a namespace will be created under the user name. The collections are stored in the namespace. You can have more than one collection in a single namespace.
namespace -> collection 1 -> role1 -> role2 -> plugin -> collection 2 -> collection N
Namespace helps you in isolating the project. When you refer to the collection in the playbook you can use the fully qualified collection name (FQCN). More about this in the coming section.
Installing Ansible Collections Locally
By default when you install collections ansible will try to pull them from ansible-galaxy. If you want to pull it from a different distribution server you have to configure the galaxy client. Let’s stick with ansible-galaxy as the distribution server for this article.
Navigate to the galaxy website. The first page shows the most popular areas.
You can navigate to the search section and type any collections. Let's say you want a collection for "MongoDB" database, type the database name in the search option and press enter.
Let’s take the first result from the search. You can get the following details.
- Collection namespace name.
- List of modules, roles, and plugins.
- The total number of downloads.
- Current collection version.
- Collection documentation and link to source code in github or any version control system.
Based on the popularity of the collection, you can download it. Let’s go ahead with the community.mongodb collection.
You can get the installation command from the collections page. You have two options.
- Run the install command which will pull and install the collection.
- Download the tarball and do a local install.
Run the following command to install the package. It will automatically take care of dependencies.
$ ansible-galaxy collection install namespace.collection
# Install mongodb collection $ ansible-galaxy collection install community.mongodb
When you install a collection, Ansible will create related directories in the user’s home directory and download the collection to it.
You can also download the tarball and install the collection locally.
# SYNTAX ansible-galaxy collection install filename.tar.gz
# command ansible-galaxy collection install community-mongodb-1.5.1.tar.gz
Installing Collections Locally with Different Versions
You can specify which version of the collection to be installed. You can choose the install version from the galaxy website and accordingly the install command will be automatically changed.
You can also use the following range identifiers.
|*||The most recent version. This is the default behavior.|
|==||Installs the specified version.|
|!=||Not equals the version specified.|
|>||Greater than the version specified.|
|>=||Greater than or equal to the version specified|
|<||Less than the version specified|
|<=||Less than or equal to the version specified.|
|,||To specify multiple conditions|
Suppose you wish to install the most recent version between V1 and V2, then the command goes like below.
$ ansible-galaxy collection install 'community.mongodb:>=1.0.0,<2.0.0'
The latest version at the time of writing this article is 1.5.1 and ansible installed it when I ran the above command.
Install Collections using Requirements File
If you have worked with Python, you should know the use of the requirements file. Similarly, we can create the requirement file to install multiple collections with a single command.
Create a file called "
requirements.yml" and add the following snippet. Here I am installing the collection from github and the galaxy website.
--- collections: - name: https://github.com/ansible-collections/community.docker type: git version: main - name: fortinet.fortiswitch version: 1.1.0 source: https://galaxy.ansible.com/
Run the following command to install the collections.
$ ansible-galaxy install -r requirements.yml
Download Collection for Offline Install
You can also download the collection along with the dependencies using the "
download" command. This will automatically generate the
requirements.yml file under the
You can now install the collections from the generated requirements file.
Different Collection Directory
You can install the collection in a different directory by using the
-p flag and passing the directory name as the argument.
$ ansible-galaxy collection install community.docker -p ~/ansible_test_collection/ Starting galaxy collection install process [WARNING]: The specified collections path '/home/ansuser/ansible_test_collection' is not part of the configured Ansible collections paths '/home/ansuser/.ansible/collections:/usr/share/ansible/collections'. The installed collection won't be picked up in an Ansible run. Process install dependency map Starting collection install process Downloading https://galaxy.ansible.com/download/community-docker-3.4.3.tar.gz to /home/ansuser/.ansible/tmp/ansible-local-21443ehap2roq/tmpn4odb5n8/community-docker-3.4.3-loe0190d Installing 'community.docker:3.4.3' to '/home/ansuser/ansible_test_collection/ansible_collections/community/docker' community.docker:3.4.3 was installed successfully
You can look at the above output which shows a warning message. Ansible uses the "
COLLECTIONS_PATH" configuration from the ansible.cfg file to search for the collections in the configured path. You have to explicitly add the other collections directory to the configuration for the playbooks to run successfully.
# ansible.cfg COLLECTIONS_PATH = ~/.ansible/collections:~/ansible_test_collection/
List Installed Collections
You can get the list of collections installed by running the following command. This will show you the collections installed with your ansible distribution as well as collections installed by you.
$ ansible-galaxy collection list
How to Use a Collection in Playbook
Till now we have seen how to download the collections using different methods. The main part is you have to use the collections in your playbook to perform some action.
I am using the
docker_network_info module to check the network information. This module is part of the
To use the collection I have used the "
collections" directive and passed the collection name as the argument. The first task uses the "
docker_network_info" module which will automatically get picked from the collection directive.
--- - hosts: localhost connection: local gather_facts: false collections: - community.docker tasks: - name: docker network information docker_network_info: name: anslab register: anslab_result - name: Print docker network information ansible.builtin.debug: var: anslab_result.network.Containers
In this article, we have seen what are ansible collections and different ways to install collections in your local machine. Go to the ansible-galaxy website and navigate across a few collections to understand more about its structure.