Create a Collection

Before creating a collection, check the ansible-collections git repository and/or Galaxy to determine if something has already been created.

The community collections feel as if they are a mixed bag of tricks that contain too much functionality in a single collection. Why does the community.general collection have gitlab roles? Why isn't there a community.gitlab collection? Why isn't nginx included in the community.general collection? Some of the collections are licorice all-sorts.

Namespace and Structure

All Ansible resources have a namespace, with the internal resources being prefixed with ansible.builtin. Multiple collections can share the same top-level namespace. This is useful for grouping code by technology or vendor.

group.collection

group.collection/
├── docs/
├── galaxy.yml
├── meta/
│   └── runtime.yml
├── plugins/
│   ├── modules/
│   │   └── module1.py
│   ├── inventory/
│   └── ...
├── README.md
├── roles/
│   ├── role1/
│   │   ├── files/
│   │   ├── handlers/
│   │   ├── templates/
│   │   ├── tasks/
│   │   └── vars/
│   ├── templates/
│   ├── tasks/
│   ├── role2/
│   └── ...
├── playbooks/
│   ├── files/
│   ├── vars/
│   ├── templates/
│   └── tasks/
└── tests/

The Collection structure documented above is from the Ansible site, however the projects under ansible-collections user various layouts.

The generally accepted minimal requirements are:

• meta/
• galaxy.yml
• README.md
• roles/ or plugins/

Word of Caution!

The playbooks directory can contain playbooks that can be included or ran directly. As a playbook must contain a valid hosts definition, in my opinion this is fraught with danger. Relying on an external playbook to do the right thing may not be a great idea.

Within internal collections it may make some sense. Such as a hccp.tenancy.settle playbook that creates the basic components required for a tenancy to be functional.

Create your first Collection

vendor.product

technology.