WORDS BY Tadej Borovšak

In August 2020, Ansible issued its first release since the developers split the core functionality from the vast majority of its modules and plugins. A few basic Ansible modules remain part of core Ansible - modules for templating configuration files, managing services, and installing packages. All the other modules and plugins found their homes in dedicated Ansible collections.

This article offers a quick look at Ansible collections in general and - especially - how to recognize high-quality ones.

What are Ansible collections?

At its core, an Ansible collection is a collection (pun intended) of related modules and plugins that you can manage independently from Ansible’s core engine. For example, the Sensu Go Ansible collection contains Ansible content for managing all aspects of Sensu Go. It includes Ansible roles for installing Sensu Go components and modules for creating, updating, and deleting monitoring resources. Another example is the Sops Ansible collection that integrates Mozilla’s Secret Operations editor with Ansible.

With the introduction of Ansible collections, Ansible Galaxy became the central hub for all Ansible content. Authors publish their Ansible collections there, and Ansible users use Ansible Galaxy’s search function to find Ansible content they need.

Ansible comes bundled with the ansible-galaxy tool for installing collections. Once you know what Ansible collection you want to install, things are relatively straightforward: Run the installation command listed on the Ansible Galaxy page. Ansible takes care of downloading and installing it. For example:

$ ansible-galaxy collection install sensu.sensu_go
Process install dependency map
Starting collection install process
Installing 'sensu.sensu_go:1.7.1' to
'/home/user/.ansible/collections/ansible_collections/sensu/sensu_go'

But finding the Ansible collection you need and vetting its contents are the harder parts.

How to select an Ansible collection

In the old times of monolithic Ansible, using third-party Ansible modules and plugins was not for the faint of heart. As a result, most users used whatever came bundled with their version of Ansible.

The ability to install Ansible collections offered a lot more control over the content you use in your Ansible playbooks. You can install the core Ansible engine and then equip it with the modules, plugins, and roles you need. But, as always, with great power comes great responsibility.

Now users are solely responsible for the quality of content they use to build Ansible playbooks. But how can you separate high-quality content from the rest? Here are five things to check when evaluating an Ansible collection.

1. Documentation

Once you find a potential candidate on Ansible Galaxy, check its documentation first. In an ideal world, each Ansible collection would have a dedicated documentation site. For example, the Sensu Go and F5 Networks Ansible collections have them. Most other Ansible collections come only with a README file, but this will change for the better once the documentation tools mature.

The Ansible collection’s documentation should contain at least a quickstart tutorial with installation instructions. This part of the documentation aims to have users up and running in a matter of minutes. For example, the Sensu Go Ansible collection has a dedicated quickstart guide, while the Sops Ansible collection includes this information in its README file.

Another essential part of the documentation is a detailed module, plugin, and role reference guide. Collection authors do not always publish those guides on the internet, but they should always be accessible with the ansible-doc tool.

$ ansible-doc community.sops.sops_encrypt
> SOPS_ENCRYPT    (/home/tadej/.ansible/collections/ansible>

        Allows to encrypt binary data (Base64 encoded), text
        data, JSON or YAML data with sops.

  * This module is maintained by The Ansible Community
OPTIONS (= is mandatory):

- attributes
        The attributes the resulting file or directory should
        have.
        To get supported flags look at the man page for
        `chattr' on the target system.
        This string should contain the attributes in the same
        order as the one displayed by `lsattr'.
        The `=' operator is assumed as default, otherwise `+'
        or `-' operators need to be included in the string.
        (Aliases: attr)[Default: (null)]
        type: str
        version_added: 2.3
...

2. Playbook readability

An Ansible playbook should serve as a human-readable description of the desired state. To achieve that, modules from the Ansible collection under evaluation should have a consistent user interface and descriptive parameter names.

For example, if Ansible modules interact with a web service, authentication parameters should be separated from the rest. And all modules should use the same authentication parameters if possible.

- name: Create a check that runs every 30 seconds
  sensu.sensu_go.check:
    auth: &auth
      url: https://my.sensu.host:8080
      user: demo
      password: demo-pass
    name: check
    command: check-cpu.sh -w 75 -c 90
    interval: 30
    publish: true

- name: Create a filter
  sensu.sensu_go.filter:
     # Reuse the authentication data from before
    auth: *auth
    name: filter
    action: deny
    expressions:
      - event.check.interval == 10
      - event.check.occurrences == 1

3. Basic functionality

Before you start using third-party Ansible content in production, always check each Ansible module’s basic functionality.

Probably the most critical property to look for is the result. Ansible modules and roles that enforce a state are much easier to use than their action-executing counterparts. This is because you can update your Ansible playbook and rerun it without risking a significant breakage.

- name: Command module executes an action -> fails on re-run
  ansible.builtin.command: useradd demo

- name: User module enforces a state -> safe to re-run
  ansible.builtin.user:
    name: demo

You should also expect support for check mode, which simulates the change without making it. If you combine check mode with state enforcement, you get a configuration drift detector for free.

$ ansible-playbook --check playbook.yaml

PLAY [host] ************************************************

TASK [Create user] *****************************************
ok: [host]

...

PLAY RECAP *************************************************
host        : ok=5    changed=2    unreachable=0    failed=0
                      skipped=3        rescued=0   ignored=0

4. Implementation robustness

A robustness check is a bit harder to perform if you’ve never developed an Ansible module or role before. Checking the continuous integration/continuous delivery (CI/CD) configuration files should give you a general idea of what is tested. Finding ansible-test and molecule commands in the test suite is an excellent sign.

5. Maintenance

During your evaluation, you should also take a look at the issue tracker and development activity. Finding old issues with no response from maintainers is one sign of a poorly maintained Ansible collection.

Judging the health of a collection by the development activity is a bit trickier. No commits in the last year are a sure sign of an unmaintained Ansible collection because the Ansible ecosystem is developing rapidly. Seeing a few commits per month is usually a sign of a mature project that receives timely updates.

Time well-spent

Evaluating Ansible collections is not an entirely trivial task. Hopefully, these tips will make your selection process somewhat more manageable. It does take time and effort to find the appropriate content for your use case. But with automation becoming an integral part of almost everything, all this effort is well-spent and will pay dividends in the future.

If you are thinking about creating your own Ansible Collection, you can download a free e-book from Steampunk packed full of advice on building and maintaining high-quality Ansible integrations.