Creating and Consuming Collections

If you were familiar with Ansible releases before 2.9, so far, much of this book will have looked very familiar to you. If you’re a newcomer to the world of Ansible automation, then, of course, all of this will look new and shiny. Regardless of your experience with Ansible to date, no book on this would be complete without an in-depth look at collections. Collections are the solution to the problems that started to manifest as a result of Ansible’s own popularity and success, and they are now at the heart of every modern Ansible installation. Whether you realized it or not, you’ve been working with them throughout this book so far, and they are here to stay, so it benefits us to take a deep dive into them.

In this chapter, we will explore collections in depth, looking in more detail at the problem that they solve and how they came about, before taking a more technical look at their structure and makeup. We will conclude the...

Technical requirements

This chapter assumes that you have set up your control host with Ansible, as detailed in Chapter 1, Getting Started with Ansible, and are using the most recent version available – the examples in this chapter were tested with Ansible 8.0 and ansible-core 2.15. This chapter also assumes that you have at least one additional host to test against, and this should be Linux-based. Although we will give specific examples of hostnames in this chapter, you are free to substitute them with your own hostnames and/or IP addresses, and details of how to do this will be provided in the appropriate places.

The code bundle for this chapter is available here: https://github.com/PacktPublishing/Practical-Ansible-Second-Edition/tree/main/Chapter 6

Introduction to Ansible collections

Although we’ve mentioned some of this earlier in this book, our goal is for this to be a complete one-stop source of information for collections – thus, if you’ve skipped directly to this chapter, don’t worry – we’ve got you covered. Let’s start with some history as this is important to understand the intention behind collections.

With Ansible releases prior to 2.9, everything was managed in one huge monolithic code base. While the core Ansible team owned this code base, the modules that really form the lifeblood of Ansible (after all, they are what enable it to automate so many disparate systems with ease) were not. Let’s say a network device vendor wanted to release a new module. Perhaps they added a new feature or fixed a bug in a prior release. They would have to make these changes, test them, and then submit them as a pull request to the main Ansible repository – not only is this...

Understanding fully qualified collection names

Before collections existed, every module that was created and contributed to Ansible had to have a unique name. Thus, it was very common to see modules named like this (both were taken from the Ansible 2.8 release):

• ios_bgp
• eos_bgp
• fortios_router_bgp

All three of these modules are to modify the Border Gateway Protocol (BGP) configuration of network devices, but they all have the device name added in front of bgp to do the following:

• Ensure their names are unique
• Ensure Ansible coders can understand what their code does

Collections remove the need for unique module names, so it is now possible for contributors to create modules with names that overlap. This is valuable because it removes the need for such long and verbose module names, but it creates the risk of unexpected code behavior. For example, we often use the debug module to understand what our playbook code does and print something out...

Managing collections on your control node

As we discussed in Chapter 1, Getting Started with Ansible, when you install Ansible, it actually installs a set of collections, providing equivalent functionality to the latest 2.x release so that backward compatibility is maintained (alongside ansible-core, of course). This process is invisible to the user, and this accompanying collection set also gets updated as you update your Ansible installation.

Given this, you could be forgiven for wondering why you need to learn about managing collections at all – after all, Ansible comes with a huge set by default, and the collections get updated as you update your installation. Yet this is the beauty of collections – if they do exactly what you need to do, then you need to take further action. In contrast, if you actually do need to extend the functionality of your Ansible control node, you can do just that – the power lies in the choice and flexibility, just as it always...

Updating your Ansible collections and core installation

You may very well be asking what happens to the collections you installed at the time of installing Ansible – how do you maintain or upgrade them? Naturally, one way is to wait for the next release of the ansible package, and then upgrade it with pip – however, this is a brute-force method and may not provide you with the results you are looking for. Let’s take a more fine-grained approach.

Let’s say you want to get access to the latest features in the amazon.aws collection, which is bundled with the ansible package when you install it – you would simply install it (again!) as follows:

$ ansible-galaxy collection install amazon.aws
Starting galaxy collection install process
Process install dependency map
Starting collection install process
Downloading https://galaxy.ansible.com/download/amazon-aws-6.1.0.tar.gz to /home/james/.ansible/tmp/ansible-local-12589si7_q1d/tmpytach2d5/amazon-aws...

Creating your own collections

We have learned a great deal about collections and how to manage and maintain them. Let’s now complete your knowledge on this topic by creating your own one from scratch, thus giving you a full overview of how they are put together and how they work.

As with roles (see Chapter 4, Playbooks and Roles), collections are simply an organized set of files within directories. Although you can look up all these directories and create them by hand, we can also get the ansible-galaxy utility to create a blank template for us to work with.

Let’s start with the fundamentals. We know that we need both a namespace and a collection name. If we publish on the Ansible Galaxy website, then the namespace will be our GitHub handle, as Ansible Galaxy takes this and uses it as your namespace. In our case, we won’t be publishing to Ansible Galaxy, so I’ll choose the namespace practicalansible, but feel free to substitute this with your GitHub...

Summary

Collections are now a vitally important part of Ansible’s overall architecture, and they provide an easy and effective mechanism for all code to be distributed and managed on control nodes everywhere. Learning about collections is vital to your understanding of the architecture of any modern version of Ansible, and armed with this information, you can manage, build, and maintain collections on your control nodes, even contributing them back to the community if you so desire.

In this chapter, you learned about the history of collections, how they came about, and why they are so important to Ansible. You then learned how to reference objects from within collections using FQCNs, before moving on to learning about the installation and management of collections on your control node. Finally, we looked at the process involved in building, installing, and testing your own collection, such that you can progress to contributing collections to the wider Ansible community if...

Questions

1. Collections are an optional feature of Ansible versions later than 2.9:
   1. True
   2. False
2. What does the acronym FQCN stand for?
   1. Fully Qualified Collection Namespace
   2. Fully Qualified Control Node
   3. Fully Qualified Collection Name
   4. Fully Qualified Control Name
3. Collections are installed and managed with which command?
   1. ansible-galaxy
   2. ansible-collection
   3. ansible
   4. collection-manager

Further reading

ansible-galaxy and its documentation can be found here: https://galaxy.ansible.com/docs/