Getting Started with Ansible Collections

Gineesh Madapparambath

4 years ago

Ansible Collection is a great way of getting content contributions from various Ansible Developers. Earlier there was a tagline for Ansible – “Batteries included”, but now the battery is a bit small I will say as default Ansible installation will still include the necessary libraries and modules needed for your automation kickstart but not the entire Ansible module and libraries. This is good in a way that Ansible developers don’t need to wait for a specific release cycle of Ansible to include their latest version of module or library; instead they can distribute their content and make available latest versions via Ansible Collections separately.

Image : unsplash.com/@bright

Find Ansible Guides to start your Ansible Automation journey

Before I go to a demo, let me explain some important directories inside the Ansible Collections.

docs/ this is the local documentation about th collection.
modules/ – ansible modules for this collection
galaxy.yml – this is the source data
playbooks/ – playbooks part of collection
lookups/ – lookup plugins
roles/ – ansible roles for this collection
tasks/ task list files for include_tasks/import_tasks
plugins/ – ansible plugins and modules for this collection
filters/ – Jinja2 filter plugins
connection/ – connection plugins (if not using default)
tests/ – tests for the collection’s content

Subscribe to YouTube Channel

So basically, Ansible Collections are like Ansible Roles but much more than that. In Ansible Role you have items like variables, handlers, tasks, templates, files etc. But in Ansible Collection you have more items like modules, plugins, filters and Ansible Roles. (It is not mandatory that, every collection will have each and every items explained above; it depends on collection purpose and content type.)

Let me explain Ansible Collections with an example

Let’s say I need to implement some automation for kubernete clusters in our organization and I know there are several k8s modules I can use in my playbooks. So I simply developed a playbook based on k8s modules and tried to run it.

ERROR! couldn't resolve module/action 'community.kubernetes.k8s_scale'. This often indicates a misspelling, missing collection, or incorrect module path.

The error appears to be in '/home/devops/ansible-collections-demo/k8s-test.yaml': line 6, column 7, but may
be elsewhere in the file depending on the exact syntax problem.

The offending line appears to be:


    - name: Scale deployment up, and extend timeout
      ^ here

Upon checking I found that k8s modules are not part of default Ansible installation, instead k8s modules and plugins are part of an Ansible Collection called community.kubernetes.

How to Install Ansible Collection

So I visited Ansible Galaxy and searched for kubernetes and I can see there are several results. But I already knew that, I need to install the kubernetes collections by community.

So I scroll down and find the community author and the kubernetes collection under that.

Click on the Kubernetes collections by Community and see the details like version, how to install this collection etc.

Now I know how to install this collection but hold on. I cannot blindly run the ansible-galaxy command to install this collection as I need to know where this collection will be installed, right ? Okay, by default, Ansible collections will be installed under ~/.ansible/collections, means in your home directory. It is fine if you are the only developer managing and running the project and only from your machine. But if you want other developers to use your ansible playbook, then they need to do the same collection installation on their machine as well ! So, if you want to deploy the collection as part of your project, install it in your project directory itself, under a specific directory.

So, I have created a directory called collections in my project directory as below.

$ pwd
/home/devops/ansible-collections-demo
$ mkdir collections
$ ls -l
total 8
drwxrwxr-x 2 devops devops 4096 Dec 22 22:28 collections
-rw-rw-r-- 1 devops devops  288 Dec 22 22:09 k8s-test.yaml

Then I install Ansible Collection by mentioning the path to be installed.

$ ansible-galaxy collection install community.kubernetes -p ./collections
[WARNING]: The specified collections path '/home/devops/ansible-collections-
demo/collections' is not part of the configured Ansible collections paths
'/home/devops/.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
Installing 'community.kubernetes:1.1.1' to '/home/devops/ansible-collections-demo/collections/ansible_collections/community/kubernetes'

You should notice two main items from the above output.

Point No. 1

The installed path – /home/devops/ansible-collections-demo/collections – is not part of ansible configuration and even if you have installed collections in your project directory, ansible will not detect it. So you need to configure your COLLECTIONS_PATHS in your ansible.cfg (for specific project).

COLLECTIONS_PATHS = ./collections

Ansible will search for collections in ~/.ansible/collections:/usr/share/ansible/collections, which is the default value for COLLECTIONS_PATHS.

Point No. 2

Ansible will automatically create a subdirectory called ansible_collections under the directory you mentioned. (And additional sub-directories based on the author name like community, fortinet, ansible etc)

$ ls -l  
total 12
drwxrwxr-x 3 devops devops 4096 Sep 22 10:40 ansible
drwxrwxr-x 3 devops devops 4096 Dec 22 22:22 community
drwxr-xr-x 3 devops devops 4096 Sep 22 10:40 fortinet

Great! I have installed an ansible collection called and let me verify the same.

$ ansible-galaxy collection list

# /home/devops/ansible-collections-demo/collections/ansible_collections
Collection           Version
-------------------- -------
community.kubernetes 1.1.1

That’s it, you can install any ansible collection in the same way and use the modules and plugins in your playbook.

Installing a specific version of Ansible Collection

There are several cases where you want to use a specific version of an Ansible collection due to compatibility issue or something. Do not need to worry as you can simply mention the collection version as below.

ansible-galaxy collection install author.newcollection:==1.0.0

Installing Ansible Collection from a Git Repository

What if your collection is not in Ansible Galaxy but it is stored in a git repository ? Again, you can deploy an Ansible Collection from a git repository as below.

ansible-galaxy collection install git+https://github.com/mycompany/mycollection.git

You may refer official documentation for more details.