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

• Collection structure documentation

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

Action	Command/Syntax
Initialize a collection	ansible-galaxy collection init ns.coll
Build a collection	ansible-galaxy collection build
Install a collection	ansible-galaxy collection install ns.coll
Install from requirements.yml	ansible-galaxy collection install -r requirements.yml
List installed collections	ansible-galaxy collection list
Use collection module	namespace.collection.module_name: in playbook
Publish to Galaxy	ansible-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

• Ansible Collections User Guide (Official Docs)
• Collection structure
• Ansible Galaxy documentation

---