Ansible collection is a format where you can bundle the Ansible project and distribute it to others for usage. The bundle can include roles, plugins, modules, documentation, and playbooks. In the upcoming sections, I will show you how to pull an existing collection and use it in your playbook.

Collection Distribution Server

When you create a collection, you have to store it in a central repository for others to access it. Ansible has its central repository called Ansible Galaxy. You will find a variety of collections created by individuals and companies and hosted in the ansible-galaxy. You can also host your collections in a version control system or an FTP server.

If you are using the Licensed version of the Ansible automation platform you will also get access to the Redhat Ansible automation hub which is similar to ansible-galaxy but maintained by the core Redhat Ansible team.

Ansible Galaxy Find A Collection

The first thing you should do is search for the role or collection. I will use podman collections as an example throughout this article.

To find any packages, navigate to the Galaxy website and use the search bar on the main page or left-hand side pane to search for the packages.

You can also use the collections and roles tab in the left-hand pane to search for collections and roles.

You will get several options depending on the collections you are searching for. When I searched for podman I got a few different collections related to podman.

There are various factors in deciding a suitable collection.

• Number of modules, roles, and plugins.
• Creator of the collection.
• Collection update frequency.
• Download count.

I will go with the first option which has more modules and plugins. This is a complete package for podman.

Ansible Galaxy Collection Interface

When you further navigate into the collection, you will get a lot of information about the collection.

Ansible Galaxy Namespace

Namespace gives you an isolated environment to create collections. Let’s say you create a collection called samplecollection and another user is also creating a collection called samplecollection. Now a conflict will arise without namspace. With a namespace, users can have collections with the same name inside the namespace which will prevent conflicts.

# WITH NAMESPACE
USER1/samplecollection
USER2/samplecollection

When you use the collection in the playbook you can use the fully qualified collection name to avoid conflicts.

user1.samplecollection.module
user2.samplecollection.module

In the case of podman, the namespace is called ‘containers’.

NOTE: Recommended practice is to use the fully qualified collection name in ansible tasks.

Ansible Galaxy Command

When you install ansible-core or ansible-navigator the ansible-galaxy command will be automatically installed. The ansible-galaxy command can be used to work with collections and create role templates.

Use the --help flag to access the help section for the ansible-galaxy command.

$ ansible-galaxy --help

There are subhelp commands for both collection and role. Since we are discussing collection let’s skip the role part.

$ ansible-galaxy collection --help

Install Ansible Collection Through Ansible Galaxy Command

You can get the command to install a collection from the Galaxy website. For example, to install podman I can get the command from the podman collections page.

You can also choose to install a different version of a collection. Choose the version from the drop-down and the command will be adjusted accordingly.

The collections will be installed in the user home directory(/home/user/.ansible/collections) by default.

Installing 'containers.podman:1.10.3' to '/home/dro/.ansible/collections/ansible_collections/containers/podman'
containers.podman:1.10.3 was installed successfully

Install Ansible Collection In Custom Path

The default behaviour of the ansible-galaxy command is to install the collection under the user’s home directory. But you can also install it in a custom path using the -p flag.

$ mkdir ~/custom_collection_path
$ ansible-galaxy collection install containers.podman -p ~/custom_collection_path

Installing 'containers.podman:1.10.3' to '/home/dro/custom_collection_path/ansible_collections/containers/podman'
containers.podman:1.10.3 was installed successfully

Install Ansible Collection Through Tar File

Download the tarball from the ansible-galaxy website.

Run the following command to install the collection directly from the tarball. This will extract the tarball and install the collection in the default or custom path.

$ ansible-galaxy collection install file-name.tar.gz  # Default collection path
$ ansible-galaxy collection install -p <custom-path> file-name.tar.gz  # Custom collection path

Install Ansible Collection Through The Requirements File

You can create a requirements.yml file and install collections through it. You can add the collection name, version, and source from which the collection is to be installed.

---
collections:
  - name: containers.podman
    version: 1.10.3
    source: https://galaxy.ansible.com/

Run the following command to install the collection through the requirement file.

$ ansible-galaxy install -r requirements.yml

List Installed Ansible Collection

You can run the following command to check the list of installed collections. This will display collections only from the default path.

$ ansible-galaxy collection list

# /home/dro/.ansible/collections/ansible_collections
Collection        Version
----------------- -------
containers.podman 1.10.3 

The following command will display the currently configured Ansible collection path. By default, it will search under your home directory(/home/user/.ansible/collections) and system directory(/usr/share/ansible/collections/).

$ ansible --version | grep -i "ansible collection location"
  ansible collection location = /home/dro/.ansible/collections:/usr/share/ansible/collections

You can add the custom collection path to ansible.cfg file too.

collections_paths = <collection-path> 

How To Use Ansible Collection In Playbook

Let’s create a simple playbook to pull podman ‘hello image’ using the podman collection.

STEP 1 – Create a new project directory.

$ mkdir ~/ansible_podman

STEP 2 – Create ansible configuration file for this project. An important parameter to note is the ‘collections_path’. If you have any custom collections path add it to the collection_path parameter.

cat > ansible.cfg
[defaults]
inventory = ./hosts
host_key_checking = False
nocows = 1
actions_warnings = False
interpreter_python = auto_silent  
collections_paths = /home/dro/.ansible/collections:/home/dro/custom_collection_path

STEP 3 – Create an inventory file. We will test the playbook on localhost with a local connection.

echo "localhost" > hosts

STEP 4 – Create the playbook and add the following play. There is only one task that uses the podman_image module from podman collections to pull the ‘quay.io/podman/hello/ ‘ image. Here I have used the fully qualified collection name(FQCN). Ansible will search for the collection through the default collection path or in the custom path configured in Ansible.cfg file.

RELATED ARTICLE – https://devrunops.com/run-ansible-playbook-locally/

--- 
- name: Podman playbook
  hosts: localhost
  connection: local
  gather_facts: false
  tasks:
    - name: Pull an image
      containers.podman.podman_image:
        name: quay.io/podman/hello

STEP 5 – Check for syntax errors by running the following command.

$ ansible-playbook --syntax-check playbook.yml

STEP 6 – Run the playbook using the ansible-playbook command.

$ ansible-playbook playbook.yml

RELATED ARTICLE : How To Setup VSCode For Ansible Development

Ansible Collections Using Ansible Navigator

Using ansible-navigator you can view the list of collections either in the localhost or in ansible execution environment.

$ ansible-navigator collections

  Name                    Version     Shadowed     Type           Path
0│ansible.builtin         2.15.3      False        contained      /usr/local/lib/python3.11/site-packages/ansible

You can also use the TUI to view the collections.

$ ansible-navigator
:collections

Wrap-Up

In this guide, I have shown you what an is ansible collection and how to get a collection from the Ansible Galaxy website. Finally, I have shown you how to configure a custom collection path in Ansible.cfg file and use the collection inside the playbook.