Explanation of Ansible Content Collections

Introductions

What Are Ansible Content Collections?

Ansible Content Collections are a structured approach within the Ansible ecosystem for organising and distributing automation resources.

They bundle together modules, plugins, roles, documentation, and other related files into a reusable and independently managed unit, allowing users to easily access and utilise the necessary resources.

Core Components of a Content Collection:

  • Modules: Small scripts that perform specific tasks, such as managing files or installing software.

  • Plugins: Pluggable components that extend Ansible’s functionality, such as callback plugins or filter plugins.

  • Roles: Structured directories used to organise and reuse automation tasks.

  • Documentation and Examples: Includes usage guides, YAML example files, and other resources to help users understand and implement the collection effectively.

Advantages

  • Modularity and Decoupling: Separates resources from the Ansible core, allowing independent updates.

  • Ease of Distribution and Management: Enables quick installation and management of collections using the ansible-galaxy command.

  • Namespace Support: Utilises the namespace.collection_name structure to prevent naming conflicts.

  • Community-Driven: Developers and organisations can share content collections, fostering the growth of the open-source ecosystem.

Differences Between Using Content Collections and the Traditional Approach

Before the introduction of Ansible Content Collections, Ansible relied on role directory structures and core module packages.

This traditional approach had several limitations:

  • Difficult Module Updates: All modules were bundled with the Ansible core version, meaning that updating a module required upgrading the entire Ansible version.

  • Lack of Flexibility: Roles and modules were managed separately, requiring users to handle multiple independent resources manually.

In contrast, Content Collections unify these resources by packaging modules, plugins, roles, and documentation into a single, standalone distribution unit. This design eliminates the limitations of the traditional approach, making automation more modular, flexible, and easier to manage.

Namespace

Why Are Namespaces Needed?

To make it easier to specify collections and their contents by name, collection names are organized into namespaces.

The introduction of namespaces helps prevent conflicts and improve organisation when managing Ansible content.

In the early stages of Ansible’s development, all modules, plugins, and roles were structured in a flat manner, leading to several issues:

  • Naming Conflicts: Different developers might create modules or roles with the same name, causing conflicts and confusion.

  • Difficult Organisation and Management: As the Ansible ecosystem expanded, the growing number of resources became harder to manage without a structured hierarchy.

With namespaces, Ansible creates separate logical spaces for different sources, such as individual developers or organisations. Using the structure namespace.collection_name.module_name, resources are ensured to be unique while also improving code readability and maintainability.

The namespace is the first part of a collection name. For example, all the collections that the Ansible community maintain are in the community namespace, and have names such as
community.crypto, community.postgresql, and community.rabbitmq. Collections that Red Hat maintain and support might use the redhat namespace, and have names such as redhat.rhv, redhat.satellite, and redhat.insights.

Names of namespaces are limited to ASCII lowercase letters, numbers, and underscores, must be at least two characters long, and must not start with an underscore.

Accessing Ansible Content Collection Documentation

Use the ansible-navigator collections command to list the collections available in automation execution environments. Type a colon before the collection number, you could check the number x line available module. Enter the module number to access its documentation.

1
2
3
4
5
6
7
8
9
10
11
  Name                    Version Shadowed Type      Path
0│amazon.aws              3.2.0   False    contained /usr/share/ansible/collec
1│ansible.builtin         2.13.3  False    contained /usr/lib/python3.9/site-p
2│ansible.controller      4.2.1   False    contained /usr/share/ansible/collec
3│ansible.netcommon       3.0.0   False    contained /usr/share/ansible/collec
4│ansible.network         1.2.0   False    contained /usr/share/ansible/collec
5│ansible.posix           1.3.0   False    contained /usr/share/ansible/collec
6│ansible.security        1.0.0   False    contained /usr/share/ansible/collec
7│ansible.utils           2.6.1   False    contained /usr/share/ansible/collec
8│ansible.windows         1.9.0   False    contained /usr/share/ansible/collec
9│ansible.yang            1.0.0   False    contained /usr/share/ansible/collec

Use the following command to display the help documentation in plain text format:

1
ansible-navigator doc <module_name> -m stdout

E.g.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
[student@workstation ~]$ ansible-navigator doc redhat.insights.insights_register \
> --mode stdout
> REDHAT.INSIGHTS.INSIGHTS_REGISTER    (/usr/share/ansible/collections/ansible_>

        This module will check the current registration status,
        unregister if needed, and then register the insights client
        (and update the display_name if needed)

OPTIONS (= is mandatory):

- display_name
        This option is here to enable registering with a display_name
        outside of using a configuration file. Some may be used to
        doing it this way so I left this in as an optional parameter.
        [Default: (null)]
        type: str

Using Ansible Content Collections in Playbooks

To use a module or a role from a collection, refer to it with its fully qualified collection name (FQCN).
For example, use redhat.insights.insights_register to refer to the insights_register module.

1
2
3
4
5
6
7
8
9
---
- name: Register new systems
  hosts: db.example.com

  tasks:
    - name: Ensure the new system is registered with Red Hat Insights
      redhat.insights.insights_register:
        state: present
        force_reregister: true

The play in the following playbook uses the organizations role from the redhat.satellite collection.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
---
- name: Add the test organizations to Red Hat Satellite
  hosts: localhost

  tasks:
    - name: Ensure the organizations exist
      ansible.builtin.include_role:
        name: redhat.satellite.organizations
      vars:
        satellite_server_url: https://sat.example.com
        satellite_username: admin
        satellite_password: Sup3r53cr3t
        satellite_organizations:
          - name: test1
            label: tst1
            state: present

Many Ansible Content Collections also use this redirection mechanism to translate old short names into Fully Qualified Collection Names (FQCN).

For example, the acl module is now part of the ansible.posix collection, and it uses ansible.posix.acl as its FQCN.

Using the Built-in Ansible Content Collection

Ansible always includes a special collection named ansible.builtin. This collection includes a set of common modules, such as copy, template, file, yum, command, and service.

You can use the short names of these modules in your playbooks. For example, you can use file to refer to the ansible.builtin.file module.

However, Red Hat recommends that you use the FQCN notation to prevent conflicts with collections that might use the same module names.