Ansible Collections: Complete Guide

Ansible Collections are a key concept in the modern Ansible ecosystem. They allow you to package and distribute sets of related Ansible content, such as roles, playbooks, modules, plugins, and more. Collections simplify the way you organize and share Ansible content across different environments and use cases.

In this comprehensive guide, we will cover everything you need to know about Ansible Collections, from the basics to advanced usage. By the end of this guide, you will have a deep understanding of collections and how they fit into the larger Ansible automation framework.

1. What is an Ansible Collection?

An Ansible Collection is a distribution format that packages related Ansible content. It can include:

• Modules: Scripts that perform a specific task (e.g., managing a service or a file).
• Plugins: Extend Ansible functionality for things like connection methods, filters, or inventory sources.
• Roles: Reusable components for organizing tasks, files, and handlers.
• Playbooks: A list of tasks and configuration that are executed against a set of managed hosts.
• Documentation: Guides and references on how to use the collection.
• Variables: Variables that are bundled within the collection for reusability.

Collections provide a standard way to package and distribute automation content, making it easy to share and use content from different sources.

2. Benefits of Using Collections

• Modularization: Collections allow you to break down large automation tasks into modular, reusable components.
• Ease of Distribution: With collections, you can package and share your automation content across environments, teams, and organizations.
• Standardization: Collections help standardize Ansible content, making it easier to manage and use.
• Versioning: You can version collections, ensuring that you can track changes and manage compatibility.
• Integration with Ansible Galaxy: Collections are distributed through Ansible Galaxy, a central hub for finding, sharing, and reusing automation content.

3. Structure of an Ansible Collection

A collection is a directory that contains a specific set of files and subdirectories. Here's what the basic structure looks like:

my_collection/
├── docs/
│   └── my_collection.rst
├── roles/
│   └── my_role/
│       ├── tasks/
│       ├── files/
│       ├── templates/
│       └── handlers/
├── plugins/
│   ├── modules/
│   │   └── my_module.py
│   ├── connection/
│   └── inventory/
├── playbooks/
│   └── my_playbook.yml
├── galaxy.yml
└── README.rst

Key Components:

• docs/: Contains documentation about the collection.
• roles/: Contains one or more Ansible roles that are part of the collection.
• plugins/: Contains various plugins (modules, filters, lookup, etc.) for the collection.
• playbooks/: Contains playbooks that are part of the collection.
• galaxy.yml: Metadata file that defines the collection and its dependencies.
• README.rst: Documentation for the collection, typically outlining how to use it.

4. Creating an Ansible Collection

Creating a collection involves organizing your automation content (roles, modules, plugins, etc.) into a specific directory structure, adding metadata, and then packaging it for distribution.

4.1 Initializing a Collection

You can create a collection using the ansible-galaxy command, which helps to initialize the directory structure for your collection.

ansible-galaxy collection init my_namespace.my_collection

This command creates the following structure:

my_namespace/
└── my_collection/
    ├── docs/
    ├── plugins/
    ├── roles/
    ├── playbooks/
    ├── galaxy.yml
    └── README.rst

• my_namespace: The namespace (typically your organization or username).
• my_collection: The name of the collection.

4.2 Defining Metadata in galaxy.yml

The galaxy.yml file is crucial for defining the metadata for the collection. It includes details such as the collection name, version, dependencies, and author.

Example galaxy.yml:

namespace: my_namespace
name: my_collection
version: 1.0.0
author: Your Name
description: This is a collection that provides tasks for managing servers.
dependencies: []

5. Organizing Content Within Collections

Once the basic structure is in place, you can begin adding content to your collection.

5.1 Adding Roles

Roles are used to group tasks, handlers, templates, and other resources into reusable units. You can add roles to the roles/ directory.

Example:

my_namespace/
└── my_collection/
    └── roles/
        └── my_role/
            ├── tasks/
            ├── files/
            ├── templates/
            └── handlers/

To define tasks in your role:

# tasks/main.yml
- name: Install Apache
  apt:
    name: apache2
    state: present

5.2 Adding Modules

Modules define the logic of an Ansible task. Place your modules in the plugins/modules/ directory.

Example:

my_namespace/
└── my_collection/
    └── plugins/
        └── modules/
            └── my_module.py

Your custom module might look like this:

from ansible.module_utils.basic import AnsibleModule

def run_module():
    module = AnsibleModule(argument_spec={})
    module.exit_json(changed=True, msg="Hello from my module!")

if __name__ == '__main__':
    run_module()

5.3 Adding Plugins

Plugins enhance Ansible's functionality. You can include different types of plugins such as connection plugins, lookup plugins, and filter plugins inside the plugins/ directory.

Example:

my_namespace/
└── my_collection/
    └── plugins/
        ├── lookup/
        │   └── my_lookup.py
        ├── filter/
        │   └── my_filter.py

5.4 Adding Playbooks

You can include reusable playbooks in the playbooks/ directory.

Example:

# playbooks/install_nginx.yml
- name: Install Nginx
  hosts: all
  tasks:
    - name: Install Nginx package
      apt:
        name: nginx
        state: present

6. Using Ansible Collections

Once you've created a collection, you can use it by referencing its namespace and name. Collections are typically installed from Ansible Galaxy, but you can also install them directly from a local path or a Git repository.

6.1 Installing a Collection from Ansible Galaxy

You can install a collection from Ansible Galaxy using the ansible-galaxy CLI.

Example:

ansible-galaxy collection install my_namespace.my_collection

6.2 Using a Collection in a Playbook

After installing a collection, you can use its content in your playbooks.

Example:

---
- name: Install and configure Apache
  hosts: all
  collections:
    - my_namespace.my_collection
  roles:
    - my_role

In this example:

• my_namespace.my_collection refers to the collection that contains the role my_role.

6.3 Installing a Local Collection

You can also install a collection from a local directory using the following command:

ansible-galaxy collection install ./my_collection/

7. Distributing Collections

Once you have developed your collection, you can distribute it by publishing it to Ansible Galaxy or other platforms like GitHub.

7.1 Publishing to Ansible Galaxy

To publish a collection to Ansible Galaxy, use the following command:

ansible-galaxy collection publish ./my_namespace-my_collection-1.0.0.tar.gz

This command uploads the collection package (tar.gz) to Ansible Galaxy, making it publicly available for others to use.

8. Managing Collection Dependencies

Collections may depend on other collections, and Ansible provides a way to manage these dependencies using the dependencies key in the galaxy.yml file.

Example of galaxy.yml with dependencies:

dependencies:
  - name: community.general
    version: ">=2.0.0"

When you install your collection, Ansible will automatically install the required dependencies as well.

9. Best Practices for Using Collections

1. Organize Content Logically: Ensure roles, plugins, and other content are well-organized within the collection.
2. Use Descriptive Names: Give meaningful names to roles, modules, and other resources in your collection to improve discoverability and readability.
3. Version Collections: Use semantic versioning (major.minor.patch) to track changes in your collections.
4. Document Your Collection: Provide clear and concise documentation in README.rst and docs/ to explain how to use the collection.
5. Test Your Collection: Regularly test your collection to ensure its compatibility and functionality.

10. Conclusion

Ansible Collections provide an effective way to package, distribute, and manage automation content. They enable you to organize related roles, modules, and other resources into a single unit, making it easier to share and reuse automation content across different environments.

Key Takeaways:

• Collections are modular: They allow you to package roles, modules, plugins, and more into reusable units.
• Collections simplify distribution: They are easy to share and distribute through Ansible Galaxy or other platforms.
• Metadata: The galaxy.yml file defines collection metadata, dependencies, and versioning.
• Best practices: Organize content logically, document your collection, and version it properly to ensure consistency and usability.

By mastering collections, you can greatly enhance your Ansible automation workflows, share content easily, and make your automation environment more scalable and maintainable.