Upgrade & Secure Your Future with DevOps, SRE, DevSecOps, MLOps!

We spend hours scrolling social media and waste money on things we forget, but won’t spend 30 minutes a day earning certifications that can change our lives.
Master in DevOps, SRE, DevSecOps & MLOps by DevOpsSchool!

Learn from Guru Rajesh Kumar and double your salary in just one year.


Get Started Now!

Ansible: step-by-step tutorial on Ansible Collections

Here’s a very detailed, step-by-step tutorial on Ansible Collections—covering what they are, why you need them, how to use them, how to create your own, and key best practices and facts. This is suitable for beginners and intermediate Ansible users alike.


1. What is an Ansible Collection?

Ansible Collections are a standardized way to package, distribute, and reuse Ansible content (modules, roles, plugins, documentation, playbooks, etc.).
Introduced in Ansible 2.9+, collections are now the foundation of all Ansible automation.

A collection is:

  • A folder structure with a clear, predictable layout
  • Can contain:
    • Modules (custom tasks)
    • Roles
    • Plugins (connection, lookup, filter, etc.)
    • Playbooks and tasks
    • Documentation and tests

Think:

  • Collections = “mini-libraries” or “apps” of Ansible content
  • Similar to Python packages or Node.js modules, but for Ansible

Example:

  • ansible.builtin (core modules shipped with Ansible)
  • community.general (community-contributed modules and roles)
  • amazon.aws (all AWS cloud content)

2. Why Do We Need Ansible Collections?

Before collections:

  • Roles, modules, plugins, and playbooks were scattered and hard to version
  • Everything was bundled in the “monolithic” Ansible project

With collections:

  • Modularity: Develop and release modules/roles/plugins independently of Ansible core
  • Versioning: Each collection has its own version and changelog
  • Distribution: Publish to Ansible Galaxy, Automation Hub, or internal/private registries
  • Reusability: Share automation content across teams and projects easily
  • Isolation: Avoid conflicts by scoping dependencies per collection

3. How to Use Ansible Collections

A. Installing a Collection

  • From Ansible Galaxy (default public repo): ansible-galaxy collection install community.general
  • From Automation Hub (enterprise): ansible-galaxy collection install my_org.my_collection --server https://my_ah_url/
  • From a requirements.yml file (recommended for projects): --- collections: - name: community.general version: ">=6.0.0" - name: amazon.aws version: ">=5.0.0" ansible-galaxy collection install -r requirements.yml

B. Using Content from a Collection

Syntax for modules:

  • namespace.collection.module_name
  • Example: community.general.ini_file

Playbook example:

- name: Use a module from a collection
  hosts: localhost
  tasks:
    - name: Use the ini_file module from community.general
      community.general.ini_file:
        path: /tmp/example.ini
        section: "defaults"
        option: "enabled"
        value: "yes"
Code language: JavaScript (javascript)

Shortcuts:

  • If a collection is installed, and the FQCN (namespace.collection.module) is used, Ansible finds it automatically.
  • For roles: roles: - amazon.aws.ec2_instance

C. Listing Installed Collections

ansible-galaxy collection list
Code language: PHP (php)

D. Where are Collections Installed?

  • Default: ~/.ansible/collections/ (user), or /usr/share/ansible/collections/ (system)

4. How to Create Ansible Collections

Let’s make a new collection from scratch!

A. Prerequisites

  • Ansible installed (pip install ansible)
  • ansible-galaxy CLI available (comes with Ansible)

B. Create a Collection Skeleton

ansible-galaxy collection init my_namespace.my_collection
Code language: CSS (css)

This creates:

my_namespace/my_collection/
  plugins/
    modules/
    lookup/
    filter/
  roles/
  playbooks/
  docs/
  tests/
  README.md
  galaxy.yml
  • my_namespace is your organization or username (required)
  • my_collection is your collection name

C. Add Content

  • Add a Role: cd my_namespace/my_collection/roles ansible-galaxy role init myrole
  • Add a Module:
    Place your custom module script in plugins/modules/ (write in Python).
  • Add Plugins/Docs/Tests:
    Use the standard subfolders.

D. Update Metadata (galaxy.yml)

Set:

  • namespace
  • name
  • version
  • authors
  • description
  • dependencies (optional: specify other collections)

E. Lint and Test Your Collection

ansible-test sanity
ansible-lint roles/myrole/

F. Build Your Collection

ansible-galaxy collection build

This outputs a .tar.gz package.

G. Publish Your Collection

  • To Galaxy: ansible-galaxy collection publish my_namespace-my_collection-1.0.0.tar.gz
  • To Automation Hub:
    Upload via web UI or API.

H. Use Your Collection

  • Install it as shown above.
  • Use its modules/roles with their FQCN in your playbooks.

5. Other Advanced/Missing Info

A. Dependencies

  • Collections can depend on other collections (declare in galaxy.yml).
  • Example: dependencies: community.general: ">=6.0.0"

B. Versioning

  • Collections use semantic versioning.
  • Specify versions when installing to ensure reproducibility.

C. Private/Internal Collections

  • Use your own Galaxy server or Automation Hub to distribute proprietary content.

D. Testing

  • Use ansible-test for units, integration, sanity checks.

E. Collection Structure

F. Importing in Playbooks

  • Always use the Fully Qualified Collection Name (FQCN):
    namespace.collection.module

G. Updating Collections

  • To upgrade: ansible-galaxy collection install community.general --upgrade

6. Summary Table

ActionCommand/Syntax
Initialize a collectionansible-galaxy collection init ns.coll
Build a collectionansible-galaxy collection build
Install a collectionansible-galaxy collection install ns.coll
Install from requirements.ymlansible-galaxy collection install -r requirements.yml
List installed collectionsansible-galaxy collection list
Use collection modulenamespace.collection.module_name: in playbook
Publish to Galaxyansible-galaxy collection publish myns-mycol-1.0.0.tar.gz

7. Best Practices & Tips

  • Always version your collections and keep a changelog.
  • Use galaxy.yml to declare dependencies, authors, and metadata.
  • Use roles for reusable sets of tasks; use modules/plugins for custom logic.
  • Test and lint your content before publishing.
  • Use requirements.yml for consistent environments.

References


Subscribe
Notify of
guest
0 Comments
Newest
Oldest Most Voted
Inline Feedbacks
View all comments

Certification Courses

DevOpsSchool has introduced a series of professional certification courses designed to enhance your skills and expertise in cutting-edge technologies and methodologies. Whether you are aiming to excel in development, security, or operations, these certifications provide a comprehensive learning experience. Explore the following programs:

DevOps Certification, SRE Certification, and DevSecOps Certification by DevOpsSchool

Explore our DevOps Certification, SRE Certification, and DevSecOps Certification programs at DevOpsSchool. Gain the expertise needed to excel in your career with hands-on training and globally recognized certifications.

0
Would love your thoughts, please comment.x
()
x