Ansible Content Collection structure and its components

Now that we better understand Content Collections and their benefits let’s look at their components and folder structure.

In this lesson, you will:

• Learn about Content Collections components and metadata.
• Learn about the Collection folder structure.

Content collection components

The collection structure standardizes the grouping of different types of automation content together. Typically, a collection contains:

Roles: Roles are a group of Ansible tasks and additional files that perform a specific function, such as installing a package or configuring a web server.

Modules: Modules are reusable scripts that perform actual tasks on managed nodes, such as installing packages or copying files. Collections can include custom modules.

Plugins: Plugins are additional pieces of code that augment Ansible’s core functionality. Ansible supports several types of plugins.

Documentation: Documentation covers the collection's content, purpose, and example use cases.

Playbooks: Ready-to-use playbook examples make it easier for users to adopt and correctly implement the collections. Including playbooks in a collection is not mandatory.

Tests: Including tests in your collection is good practice and helps ensure the reliability of your content. 

Content collection metadata

Content collections also contain metadata about the collection itself. This metadata includes information on how to build the collection artifact and compatibility information, such as supported Ansible Core versions. Collection metadata is stored in two locations:

The galaxy.yml file

The galaxy.yml file contains information about the collection itself and how to build the collection artifact. The galaxy.yml file can include information such as:

• Description: A summary of the Collection’s purpose and content
• Authors: Lists the Collection creators and maintainers
• Version: Collection authors can use semantic versioning to manage upgrades and dependencies.
• Dependencies: Specifies the dependencies the Collection needs to execute successfully. Dependencies can include other Collections, roles, and modules.

The meta/runtime.yml file

The meta/runtime.yml file contains additional metadata information, such as collection compatibility and supported Ansible Core versions. It also supports more advanced configuration options, including plugin redirection and action groups. Available runtime.yml fields include:

• Requires_ansible—Specifies which versions of Ansible Core are compatible with the Collection, for example, >=2.11.10, <2.15.2.
• Plugin_routing—Manages redirects to different plugins and ensures that if a plugin is renamed or moved to a different collection, existing playbooks can still successfully reference it
• import_redirection—A mapping of names for Python import statements and their redirected locations
• action_groups—A mapping of groups and the list of action plugins and module names they contain

Please refer to the Ansible documentation for a complete list of metadata fields.

Content collection folder structure

Now that we better understand a Collection’s components, let’s look at an example of its folder structure and where these components reside:

web_collection/                 # Root folder.
├── docs/                       # Documentation
│   ├── install_webserver.md    # Docs for installing webserver                      
├── galaxy.yml                  # Collection information file.
└── meta/                       # Metadata folder
    └── runtime.yml             # Additional Collection metadata.      
├── plugins/                    # Custom Plugins folder
│   ├── modules/                # Custom modules folder
│   │   └── web_module.py       # Custom module called "web_module.py"
│   ├── inventory/              # Custom inventory scripts folder.
│   └── filter_plugins/         # Custom filter plugins folder.
├── roles/                      # Roles folder.
│   ├── web_role/               # Role named "web_role"
├── playbooks/                  # Playbooks folder.
│   ├── install_webserver.yml   # Playbook "install_webserver.yml"
├── README.md                   # Collection overview documentation.
├── LICENSE                     # Licensing information.
└── tests/                      # Collection tests folder

Example Collection folder structure.

• web_collection—The collection root folder. 
• install_webserver.md—Specific use case documentation explaining how to use the Collection.
• galaxy.yml—The metadata file containing information about the collection, such as dependencies, version, and author information.
• meta/runtime.yml—Additional collection metadata, such as compatible Ansible Core versions.
• plugins/modules/—Location of the Collection’s custom module files. In the example above, this is the web_module.py file.
• roles/—Location of the collection’s roles. The example above contains the web_role role.
• playbooks/—This folder contains the collection playbooks. This example includes the install_webserver.yml playbook.
• README.md—The main collection documentation file contains essential information such as its function and how to use it.
• LICENSE—This file specifies the terms and conditions by which the collection can be distributed.

Please have a look at the collection structure documentation for more information.

The next lesson will cover finding and installing collections and using them in playbooks.