Ansible Collections Tutorial For Beginners

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

Accessing Help

To access the help section, you can run the following commands.

$ ansible-galaxy --help

The 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.

# syntax
$ ansible-galaxy collection install namespace.collection

Example:

# 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.

/home/${USER}/.ansible/collections/ansible_collections

You can also download the tarball and install the collection locally.

# SYNTAX
ansible-galaxy collection install filename.tar.gz

Example:

# 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.

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 ./collections directory.

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 community.docker collection.

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

Conclusion

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.