Journey of the development of Ansible Collection? (Part 3)

I suggest you should read the whole series or at least start with the previous one to get the full context. Below is the link for the previous article.

Journey of the development of Ansible Collection? ( Part 2)

https://asia.si.edu/collections/

Nov 2020

What is Ansible Collection?
It is a set of similar modules which can do a couple of tasks for the given environment/region/cloud-provider/software/etc.

Why we need Ansible Collection?
Before Ansible 2.9.10 version, Ansible Modules were packed into Ansible Packages and All the modules have to meet a certain level of standard as they will be shipped with the official product and that lead serious issue which is the delay in the new modules.
After Ansible 2.9.10 version, Ansible Team decided to split modules into a separate set of collections which will do be very specific jobs for a given use case and increase the speed of the new module rollout as well.

A new pattern was created to package these modules so they can be easily plugged into Ansible and that is called Collection/Ansible Collection.

Examples:

1. https://github.com/116davinder/ansible.missing_collection
2. https://github.com/ansible-collections/community.general
3. https://github.com/ansible-collections/community.aws
4. so on

Ansible Core Team composed a document to layout basic details of the Collection and its ingredients.

Developing collections - Ansible Documentation

Let’s talk about the structure of the Ansible Collection.

$ tree -L 3
.
├── docs
│   ├── community.missing_collection.aws_amp_info_module.rst
│   ├── community.missing_collection.aws_amp_module.rst
.............
│   ├── community.missing_collection.mapr_service_module.rst
│   └── community.missing_collection.newrelic_deployment_module.rst
├── galaxy.yml
├── LICENSE
├── meta
│   └── runtime.yml
├── plugins
│   ├── modules
│   │   ├── aws_amp_info.py
│   │   ├── aws_amp.py
.............
│   │   ├── __init__.py
│   │   ├── mapr_service.py
│   │   └── newrelic_deployment.py
│   └── module_utils
│       ├── aws_response_parser.py
│       ├── __init__.py
│       └── utils.py
├── README.md
├── requirements.txt
└── tests
    ├── integration
    │   └── aws
    └── readme.md
8 directories, 387 files

galaxy.yml: It includes things like “namespace”, “name”, “version”, and so on which you should set, some of them are optional but it’s much better to just set them once and forget about it.

Notes: “community”, “ansible” and a couple of namespaces are reserved for Ansible and you can’t publish a collection with these names to Ansible Collection Website: https://galaxy.ansible.com which is similar to Docker Hub for Docker Images at http://store.docker.com.

$ cat galaxy.yml 
namespace: community
name: missing_collection
version: 0.1.0
readme: README.md
authors:
  - Davinder Pal (@116davinder) <dpsangwal@gmail.com>
description: It will contains all the modules which are missing in official ansible collections.
license_file: LICENSE
tags: [community, aws, cloud, amazon]
dependencies: null
repository: https://github.com/116davinder/ansible.missing_collection
documentation: https://github.com/116davinder/ansible.missing_collection/tree/master/docs
homepage: https://github.com/116davinder/ansible.missing_collection
issues: https://github.com/116davinder/ansible.missing_collection/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc
build_ignore:
  - '*cloud-config-aws.ini'
  - '*cloud-config-aws.yml'
  - 'changelogs/.plugin-cache.yaml'

meta/runtime.yml: It only stores the ansible required version for now.

$ cat meta/runtime.yml 
---
requires_ansible: '>=2.9.10'

LICENSE is optional things but I highly recommend you to use these one’s because someone might sell your content to others which is freely available to everyone.

README is semi-optional because later it will be used in automated doc creation and it store other important notes/links for the repository which will be used by the general user to understand your collection better.

docs is a common folder name to store auto-generated documentation for collection modules.

tests is a common folder name where you can store example/test codebase for your collection modules.

plugins/modules is where you will put your ansible modules.

plugins/module_utils is where you will put any shared code which can be used across multiple modules within the collection.

Once you are used to this structure then it becomes super easy to understand other collections and how they operate.

Please take a break and review the collections mentioned in the below link.

Contributing to Ansible-maintained Collections - Ansible Documentation

Have Fun!, I will be back soon with the next part of the series.