5 tips for choosing an Ansible collection that's right for you | Opensource.com

5 tips for choosing an Ansible collection that's right for you

Try these strategies to find and vet collections of Ansible plugins and modules before you install them.

Woman sitting in front of her computer
Image credits : 
Ray Smith

Subscribe now

Get the highlights in your inbox every week.

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

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
        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
: &auth
: https://my.sensu.host:8080
: demo
: demo-pass
: check
: check-cpu.sh -w 75 -c 90
: 30
: true

- name
: Create a filter
    # Reuse the authentication data from before
: *auth
: filter
: deny
      - 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
: useradd demo

- name
: User module enforces a state -> safe to re-run
: 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 eBook from Steampunk packed full of advice on building and maintaining high-quality Ansible integrations.

Text editor on a browser, in blue

See examples and learn the most important modules for automating everyday tasks with Ansible.
A person programming

With a tiny bit of effort, you can help the next person by not just mapping the safe path but leaving warnings about the dangers.
Science lab with beakers

Build an environment to support learning and experimenting with new software.


About the author

Tadej Borovšak - Tadej is an Ansible Evangelist at https://steampunk.si, a team that builds high-quality Ansible Collections for vendors. He works on tools that make the lives of fellow programmers and system administrators easier and has been using Ansible to automate just about everything, from physical server provisioning to serverless application deployments, and semi-regularly writes blog posts about his endeavors. Tadej is exceptionally effective at making...