Get up to 50% off on CKA, CKAD, CKS, KCNA, KCSA exams and courses!

Getting Started with Ansible Collections

Getting Started with Ansible Collections

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.

Gineesh Madapparambath

Gineesh Madapparambath

Gineesh Madapparambath is the founder of techbeatly. He is the co-author of The Kubernetes Bible, Second Edition and the author of Ansible for Real Life Automation. He has worked as a Systems Engineer, Automation Specialist, and content author. His primary focus is on Ansible Automation, Containerisation (OpenShift & Kubernetes), and Infrastructure as Code (Terraform). (Read more: iamgini.com)


Note

Disclaimer: The views expressed and the content shared in all published articles on this website are solely those of the respective authors, and they do not necessarily reflect the views of the author’s employer or the techbeatly platform. We strive to ensure the accuracy and validity of the content published on our website. However, we cannot guarantee the absolute correctness or completeness of the information provided. It is the responsibility of the readers and users of this website to verify the accuracy and appropriateness of any information or opinions expressed within the articles. If you come across any content that you believe to be incorrect or invalid, please contact us immediately so that we can address the issue promptly.

Share :

Related Posts

HashiCorp Certified Terraform Associate – Learning & Exam Tips

HashiCorp Certified Terraform Associate – Learning & Exam Tips

Introduction I started using Terraform somewhere in 2018, but very limited usage as I thought it is just another tool for provisioning infrastructure …

How to Increase Attachment File Size Limit in GitLab

How to Increase Attachment File Size Limit in GitLab

We know GitLab is one of the best and easy to use git server solutions available in the market now. And GitLab CE is available as free and we can …

Ansible Automates 2020 on 9th & 10th September

Ansible Automates 2020 on 9th & 10th September

Another good news during this unusual time as Ansible Automate 2020 is a Virtual Event this year and we all will get the chance to attend the same …