SUKAATO's Hypomnema

20250606145552-Ansible_Collections

5 min read

Ansible Collections

From bib. source

Collections allow the gathering of Ansible plugins, roles and even playbooks into one entity, in a more structured way that Ansible, Ansible Galaxy, and Automation Hub can scan and consume.

That is, Ansible collections are a way to gather plugins, roles, and even playbooks in a structured directory tree (Geerling 2023, 148). Collections are particularly useful for distributing Ansible plugins, which are Python files that can extend for the use of Jinja filters in playbooks or roles (Ibid). Jinja filters are template code written to verify or validate data (Geerling 2023, 149).

Making and using Collections

A collection is identified by its name and the namespace it exists in, the latter preceding the former but conjoined by a dot or period, such as seen in dot notation (Geerling 2023, 155). This representation is used in a command-line context, exemplified for local.colors in the following (Geerling 2023, 155-156):

ansible-galaxy collection init local.colors --init-path ./collections\/ansible_collections

This command line itself, however, also implies that, insofar as local.colors is a collection, it corresponds to a directory path ./collections/ansible_collections/local/colors. The directory path .collections/ansible_collections/${COLLECTION_NAMESPACE} has docs, plugins, and roles as sub-directories as well as a galaxy.yml YAML file (Geerling 2023, 156). Such a path can also include a README file under it (Ibid).

Regarding the galaxy.yml file in .collections/ansible_collections/${COLLECTION_NAMESPACE} (Ibid):

From bib. source

The most important thing is the galaxy.yml file which is required so Ansible can read certain metadata about the Collection when it is loaded. For local collections […], the defaults are fine, but later, if you want to contribute a collection to Ansible Galaxy and share it with others, you would need to adjust the configuration in this file.

That is, galaxy.yml specifies metadata for the collection that is useful to repositories and has sane defaults for purely local use.

Test plugins (i.e., test Python files) in a collection can be placed under a test sub-directory of the .collections/ansible_collections/${COLLECTION_NAMESPACE}/${COLLECTION_NAME}/plugins directory path (Geerling 2023, 157).

Making use of plugins in a collection can be done in two ways (Geerling 2023, 157-158):

  • Adding a collections section into the relevant playbook with an item or element in its list value, that item or element being the relevant namespace plus collection name dot notation juxtaposition, which allows one to refer to the Python filename from the associated path within the playbook
  • Referring to the collections plugin by using its FQCN, i.e. its Fully Qualified Collection Name, in the given playbook, which involves using dot notation for all modules in the collection, after the collection namespace and collection name dot notation juxtaposition.

In the first case, one would write the following in the playbook for a local.colors collection that includes a blue plugin (i.e., blue.py) (Geerling 2023, 157):

---
- hosts: all
 
  collections:
    - local.colors
 
  vars:
    my_color_choice: blue

In the second case, one could write the following, with no need of a collections section as exemplified above (Geerling 2023, 158):

tasks:
  - name: "Verify {{ my_color_choice }} is a form of blue."
    assert:
      that: my_color_choice is local.colors.blue

For clarity (Ibid):

From bib. source

Any content that you add to the collection–plugins, modules, or roles–can be called the same way. Whereas for things built into Ansible or local to your playbook you can call them with modulename or rolename, for things from collections you should call them by their FQCN.

The collections path

Note that in the above example, the directory path argument for the init-path option of the ansible-galaxy command has its first directory as ./collections/, but this part of the path is otherwise simply whatever the collections path would be as specified by the ANSIBLE_COLLECTIONS_PATH environment variable or in an ansible.cfg file for the collections_path directive (Geerling 2023, 160-161). The default paths for collections are: ~/.ansible/collections and /usr/share/ansible/collections (Geerling 2023, 161).

Downloading and installing Ansible Collections

From bib. source

Just like roles, collections can be shared with the entire community on Ansible Galaxy […]

To use collections made by others in repositories like the Ansible Galaxy as one would with Ansible roles, one uses the ansible-galaxy collection command line with sub-command install, like so (Geerling 2023, 159):

ansible-galaxy collection install geerlingguy.k8s

Similarly, one can also simply write or write into a “requirements¨ YAML file (just like with roles) for collection installations (Ibid):

---
collections:
  - name: geerlingguy.k8s

Constraints on installations

Installations through ansible-galaxy can have constraints placed on them within the YAML requirements file it uses, such as a constraint on the version that is allowed to be installed or downloaded (Geerling 2023, 160):

---
collections:
  - name: geerlingguy.k8s
    version: >=0.10.0,<0.11.0

And then install what is enlisted in it by running (Geerling 2023, 159):

ansible-galaxy install -r requirements.yml

Ansible_Galaxy templating_engine programming_languages programming_language dot_notation Jinja_filter Jinja_filters data_validation data_validator ad-hoc_command ad-hoc_commands command_line command_lines command_line_interface command_line_interfaces directory_path YAML_Aint_Markup_Language Yet_Another_Markup_Language package_manager package_management configuration_management fully_qualified_collection_name localhost loopback_address loopback_addresses directives sections

bibliography

  • “Ansible Plugins and Content Collections.” In Ansible for DevOps: Server and Configuration Management for Humans, 2nd ed., 148–62. Leanpub, 2023.

Graph View