Home Ansible Ansible Collections Tutorial For Beginners

Ansible Collections Tutorial For Beginners

How To Work With Collections In Ansible

By Karthick
6K views

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
Ansible Galaxy Help
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
Ansible Galaxy Collection Help
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.

Ansible Galaxy Webpage
Ansible Galaxy Webpage

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.

Search MongoDB Collection
Search MongoDB Collection

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.

Download community.mongodb Collection
Download 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
Collection Directory
Collection Directory

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

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

Different Collection Version
Different Collection Version

You can also use the following range identifiers.

SYMBOLUSAGE
*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
Table - Range Identifier

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 Collection using Range Identifiers
Install Collection using Range Identifiers

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
Install Collections using Requirements File
Install Collections using Requirements File

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.

Download Collections for Offline Install
Download Collections for Offline Install

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
Ansible Collection List
Ansible 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
docker_network_info Output
docker_network_info Output

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.

You May Also Like

Leave a Comment

* By using this form you agree with the storage and handling of your data by this website.

This site uses Akismet to reduce spam. Learn how your comment data is processed.

This website uses cookies to improve your experience. By using this site, we will assume that you're OK with it. Accept Read More