Ansible - Collections 1/2 (Usage)

In the past, and especially on the Chemnitz Linux Days, I was asked about Ansible Collections, a lot. It seems like this topic is somewhat complicated and still unknown.

Let's take a look at collections, build one, and showcase how it can make your development easier than ever.

In the first part, we will take a look at the usage of collections.

Ansible

Ansible is a super simple automation framework. It can be used for infrastructure-as-code, configuration management, deployments on Kubernetes and much more. For me, it is the Swiss Army Knife of automation.

Why Collections?

There are two major reasons to use and develop collections. The first one has its origin in a major revamp of the Ansible architecture. With the release of Ansible 3.0.0 the Ansible project was split into more maintainable and smaller parts.

But, it was not only about maintainability. In the past, we had to publish and maintain roles, plugins/modules and playbooks in individual repositories and use different testing tools.

With the introduction of Ansible collections, we finally had a format to put everything together. Version it properly and take care of our Ansible code in a software development way.

Therefore, a collection can contain a directory layout like:

$ tree mynamespace/
mynamespace/
└── mycollection
    ├── docs
    ├── galaxy.yml
    ├── meta
    │   └── runtime.yml
    └── playbooks
    │   └── my_playbook.yml
    ├── plugins
    │   └── README.md
    ├── README.md
    └── roles
        └── my_role

This makes it super convenient maintaining roles, playbooks, and plugins in the same repository. No more playbook repositories that reference and require a ton of other repositories.

But, there is more. What IF you require another collection or want to publish it? Well, the galaxy.yml file is there for you. Here you can define dependencies, documentation links, licenses and much more. A typical installation of an Ansible collection will install the required dependency collections, too.

And even more! Alongside the whole collection re-design, the Ansible ecosystem has gotten a new command line tool. If you want to test your plugins, roles and playbooks, the ansible-test command will get you covered.

Let's use collections

If you are using an Ansible version >= 3.0.0 or Ansible Core >= 2.11, it is likely that you are already making use of collections. Basically, all examples I have given in my articles are using collections under the hood.

Anyway, let's come up with a super simple example to make this clear.

In a playbook

First, we want to write a simple playbook. Let's install some packages and some Flatpaks on a Fedora Workstation.

---
# playbook.yml

- name: "Install packages"
  hosts: "localhost"
  
  tasks:
  
    - name: "Install Git"
      ansible.builtin.package:
        name: "git"
        state: "present"
      become: true
      
    - name: "Install Gedit"
      community.general.flatpak:
        name: "org.gnome.gedit"
        state: "present"
        method: "user"

Both of the above tasks are using modules from different collections. One is from the ansible.builtin collection, the other one is from the community.general collection.

Install collections

On a fresh installation of Ansible (the ansible-core package to be precise) you will not find the "community.general" collection. Therefore, we have to install it:

# Install a collection
$ ansible-galaxy collection install community.general

If you don't want to do this for each collection or maintain the requirements with your code, you can maintain a requirements.yaml file.

# requirements.yaml

collections:
  - name: "community.general"

Now you can install collections from this file.

# Install collections from requirements.yaml
$ ansible-galaxy collection install -r requirements.yaml

Fine, but what does this do? In general, it will download the collection and unpack it to a collection directory. For a regular user, this will be the ~/.ansible/collections. This can be tweaked, though. With the ansible-config command, you can find out all the details.

# Check the collection paths
$ ansible-config dump | grep COLLECTIONS_PATHS
COLLECTIONS_PATHS(default) = ['/var/home/dschier/.ansible/collections', '/usr/share/ansible/collections']

# Check the directory
$ ls -la ~/.ansible/collections/ansible_collections/
total 0
drwxr-xr-x. 1 dschier dschier 372 25. Apr 08:33 .
drwxr-xr-x. 1 dschier dschier  38 15. Nov 2022  ..
drwxr-xr-x. 1 dschier dschier  10 15. Nov 2022  ansible
drwxr-xr-x. 1 dschier dschier  20 15. Nov 2022  ansible.posix-1.4.0.info
drwxr-xr-x. 1 dschier dschier  28  7. Jan 09:55 community
drwxr-xr-x. 1 dschier dschier  20 15. Nov 2022  community.general-6.0.1.info

There you go.

Finding collections

Well, for many collections you will find the documentation in the Ansible docs. But, there must be more, right? Right. You can also search in the Ansible Galaxy.

There you can find hundreds of community collections with sometimes very special goals. Jeff Geerling (aka Geerlinguy) for example is maintaining a super nice PHP collection.

Docs & Links

For further reading, I strongly recommend the official documentation, but also a couple of blog articles.

Using Ansible collections — Ansible Documentation

Collection Index — Ansible Documentation

Hands on with Ansible collections

In this blog post we’ll walk through a use case wherein, the user would like to use a Red Hat certified collection from Automation Hub and also use a community supported collection from Ansible Galaxy.

Ajay Chenampara

Getting Started With Ansible Content Collections

In this blog post, we go into how to get started with Ansible Content Collections, a part of Red Hat Ansible Automation Platform.

Colin McNaughton

Conclusion

That's it for using collections. In the next article, I will give an introduction how you can create your own collection with some roles, playbooks, or even plugins.

But beforehand, please let me know: Do you already use collections or even develop your own? What do you think about the concept of collections?