Uncategorised

What is Ansible collection?

August 10, 2023 Leave a Comment

An Ansible collection is a distribution format that bundles together Ansible content such as playbooks, roles, modules, and plugins into a single package. It provides a way to organize and share Ansible content in a modular and versioned manner. Collections are designed to make it easier to manage and share reusable automation content across different projects, teams, and organizations.

In the context of Ansible, here are some key points about collections:

  1. Modularity: Collections allow you to organize Ansible content into logical units. This makes it easier to manage and share specific components of automation, like roles, modules, and plugins.
  2. Versioning: Collections can have different versions, enabling better control over the changes made to automation content. This is crucial for maintaining stability and consistency in your infrastructure automation processes.
  3. Distribution: Ansible collections can be shared through various channels, including the Ansible Galaxy community website. This encourages collaboration and the sharing of best practices among the Ansible user community.
  4. Content Types: Collections can contain various types of content, including modules (the building blocks of Ansible automation), plugins (to extend Ansible functionality), roles (pre-packaged automation tasks), and playbooks (orchestration of tasks).
  5. Dependencies: Collections can have dependencies on other collections or specific versions of Ansible. This ensures that the required automation components are available for successful execution.
  6. Namespace: Collections introduce a namespace structure to avoid naming conflicts between different authors and organizations. This helps in organizing content and avoiding clashes in names.

To use an Ansible collection, you typically install it using the ansible-galaxy command-line tool, specifying the collection name and optionally the version you want to install. Once installed, you can reference and use the content from the collection in your Ansible playbooks, roles, and other automation tasks.

Ansible collections have improved the manageability, reusability, and collaboration aspects of Ansible automation, making it easier for DevOps teams to create, share, and maintain their infrastructure-as-code solutions.

A Closer Look at Collections

An Ansible Content Collection can be described as a package format for Ansible content:

Screen Shot 2019-11-13 at 4.11.45 PM

 This format has a simple, predictable data structure, with a straightforward definition:

  • docs/: local documentation for the collection
  • galaxy.yml: source data for the MANIFEST.json that will be part of the collection package
  • playbooks/: playbooks reside here
    • tasks/: this holds ‘task list files’ for include_tasks/import_tasks usage
  • plugins/: all ansible plugins and modules go here, each in its own subdir
  • roles/: directory for ansible roles
  • tests/: tests for the collection’s content

Collection Structure 

Modules, plugins, roles, playbooks and documentation are distributed across the Ansible community as Collections. The distribution is done by Ansible Galaxy, where users can access a developer’s shared content. Ansible content is converted into a single portable Collection as a new directory structure. The following diagram shows the structure of a collection directory and its contents.

Galaxy.yml

A Collection should have a galaxy.xml containing the necessary information to build a collection artefact. It is a file at the root level of the collection that holds the metadata and tools to package and publish the collection. It contains the following keys in YAML format.

Keys in galaxy.yml

The docs directory

This folder contains information on how to use the roles and plugins provided by the collection. The structure of extra documentation and its link is defined in the docs/docsite/extra-docs.yml. The file also defines the index page’s title in the collection’s documentation. Any additional links to the plugins or the collection index pages are added to the docs/docsite/links.yml file. Plugin-specific documentation is embedded as Python docstrings. They can be accessed and viewed by using the ansible-doc command.

ansible-doc -t lookup namespace_1.collection_1.lookup_1

Here, namespace_1 is the Galaxy namespace, and collection_1 is the name of the namespace containing that collection. The galaxy namespace of the collection is defined in the galaxy.xml file.

The plugins directory

All plugins involved must be present in the collection plugins directory. These plugins are accessible to all the roles of a collection, so it distributes modules, filters and lookups without importing roles. Plugins are stored under a subdirectory known as plugin_type, which contains folders like callback_plugins, inventory_plugins, cache_plugins, strategy_plugins and many more. The plugins directory contains one prominent subdirectory called module_utils which is used by modules and plugins using a fully qualified collection name. The functions and classes of module_utils can be imported in Python using the following statement.

from ansible_collections.{namespace}.{collection}.plugins.module_utils.{util} import {something}

The roles directory

Roles help load vars, files, tasks, handlers, and other Ansible artefacts based on a given file structure. Ansible looks for roles in the roles/ directory relative to the playbook file. Collection role names start with an alpha character and can contain only lowercase characters and underscore. They can not have plugins. All the roles can access plugins from the plugins directory.

An Ansible role is composed of many folders under a directory, each containing multiple YAML files. The role name is the same as the directory name and must comply with the naming rule. 

The playbooks directory

Ansible playbooks offer reusable and repeatable configuration management and deployment systems to deploy complex and advanced applications. They can launch tasks synchronously and manage the steps of any ordered process. The playbooks directory stores all the playbooks involved in the collection. They can be accessed by their fully qualified collection name from the command line as namespace.collection.playbook or from import_playbook. The owner can store documentation for each playbook in the docs directory.

The tests directory

Testing collections ensure that the code executes correctly and integrates well with the other components of the Ansible environment. The tool used to test Ansible collections is called ansible-test. The ansible-test tool is always executed from the root directory of the collection. Users can add unit tests tests/unit/plugins/ folder and integration tests in the tests/integration/targets/ folder. Python requirements for unit tests can be specified in tests/unit/requirements.txt.

The meta-directory and runtime.yml

Additional metadata of a collection is stored in the runtime.yml file present in the meta directory. It supports top-level keys like requires-ansible, plugin_routing, import_redirection and action_groups. The requires_ansible key defines the version of the ansible-core to use the collection. Plugin_routing contains the content needed to be loaded from a location that is deprecated or removed. Mapping names for import statements in Python and their locations are specified in the import-redirection key. Action_groups contains a mapping of groups and the list of action plugins they hold.

To create a ansible collection:

  • Create a collection skeleton with the “ansible-galaxy collection init” command.
  • Add modules and other content to the collection.
  • Build the collection into a collection artifact with “ansible-galaxy collection build”.
  • Publish the collection artifact to Galaxy with “ansible-galaxy collection publish”.

Creating a collection skeleton

To start a new collection, run the following command in your collections directory:

$ ansible-galaxy collection init my_namespace.my_collection

It will create the structure [my_namespace]/[my_collection]/[collection skeleton].

Once the skeleton exists, you can populate the directories with the content you want inside the collection.

Reference: the ansible-galaxy collection command. Currently the ansible-galaxy collection command implements the following sub commands:

  • init: Create a basic collection skeleton based on the default template included with Ansible or your own template.
  • build: Create a collection artifact that can be uploaded to Galaxy or your own repository.
  • publish: Publish a built collection artifact to Galaxy.
  • install: Install one or more collections.

Reference

  • https://docs.ansible.com/ansible/latest/collections_guide/index.html

Rajesh Kumar
Follow me
Latest posts by Rajesh Kumar (see all)
Subscribe
Notify of
guest
0 Comments
Inline Feedbacks
View all comments
0
Would love your thoughts, please comment.x
()
x