Remember that Ansible organizes collections in namespaces. The namespace is the first part of a collection name. For example, the namespace of the amazon.aws collection is amazon.

Carefully choose a namespace for grouping your collections:

Use the ansible-galaxy collection init command to create the directory structure for your new collection. Specify the name of the collection, including the namespace, as the argument to the command:

[user@host ~]$ ansible-galaxy collection init mynamespace.mycollection
- Collection mynamespace.mycollection was created successfully

This command creates the collection and organizes content in the following directory and file structure:

[user@host ~]$ tree mynamespace/
mynamespace/
└── mycollection
    ├── docs 
    ├── galaxy.yml 
    ├── plugins 
    │   └── README.md
    ├── README.md 
    └── roles 

4 directories, 3 files

Organize the modules, plug-ins, and filters that you develop in subdirectories under the plugins/ directory. For modules, create the plugins/modules/ subdirectory and then copy the Python scripts for your modules into that subdirectory. For inventory plug-ins, create and then use the plugins/inventory/ subdirectory. Similarly, the other plug-in types have dedicated subdirectories. Developing modules, plug-ins, and filters is beyond the scope of this course.

If you have existing roles, then you can move their directory structure under the roles/ directory. To create a role for the collection, use the ansible-galaxy role init command from inside the roles/ directory:

[user@host ~]$ cd mynamespace/mycollection/roles/
[user@host roles]$ ansible-galaxy role init myrole
- Role myrole was created successfully
[user@host roles]$ ls myrole/
defaults  files  handlers  meta  README.md  tasks  templates  tests  vars

The galaxy.yml YAML file at the root of the collection directory provides information for Ansible to build and publish the collection. The file includes comments that describe each parameter. The following galaxy.yml file is a complete example:

---
namespace: mynamespace
name: mycollection
version: 1.0.0
readme: README.md
authors:
  - your name <example@domain.com>
description: Ansible modules to manage my company's custom software
license:
  - GPL-3.0-or-later

repository: https://git.example.com/training/my-collection

# The URL to any online docs
documentation: https://git.example.com/training/my-collection/tree/main/docs

# The URL to the homepage of the collection/project
homepage: https://git.example.com/training/my-collection

# The URL to the collection issue tracker
issues: https://git.example.com/training/my-collection/issues

dependencies:
  community.general: '>=1.0.0'
  ansible.posix: '>=1.0.0'

Some collections depend on other collections to work correctly. For example, a role in your new collection might call modules from other collections. Declare all those required collections by using the dependencies parameter in your galaxy.yml file.

That parameter is a dictionary of collections. For each entry, the key is the collection FQCN, and the value is the collection version (use >=1.0.0 when you do not need a specific version). The following example lists the community.general and ansible.posix collections as requirements:

...output omitted...
dependencies:
  community.general: '>=1.0.0'
  ansible.posix: '>=1.0.0'
...output omitted...

You do not need to declare the ansible.builtin collection.

More complex collections might provide modules, plug-ins, and filters that depend on additional Python libraries. Users must install the corresponding Python packages in the execution environment before they can use the collection. For example, the amazon.aws collection uses the Amazon Web Services Software Development Kit (SDK) that the boto Python package provides.

For those Python dependencies, create a requirements.txt file at the root of your collection. Each line of the file declares a Python package. The following example shows the content of the requirements.txt file for the amazon.aws collection. At the end of the package name, the version part is optional if you do not require a specific version.

botocore>=1.18.0
boto3>=1.15.0
boto>=2.49.0

Some collections also require system-level packages in the execution environment. For example, the ansible.posix collection requires the rsync RPM package. At the root of your collection, create the bindep.txt file and list the RPM packages, one per line. The following example shows the content of the bindep.txt file for the ansible.posix collection.

rsync [platform:centos-8 platform:rhel-8]

The bindep tool, which processes the bindep.txt file, can manage packages for several Linux distributions. Different distributions might have other package names for the same software. In the preceding file, the [platform:centos-8 platform:rhel-8] directive provides the name of the Linux distributions. Another standard directive is [platform:rpm], which targets all the Linux distributions that use the RPM packaging system.

You can define additional metadata for the collection in the meta/runtime.yml file. If your collection requires a specific version of Ansible, then add the requires_ansible parameter to the file. The following example specifies that the collection works with Ansible 2.10 or later.

---
requires_ansible: ">=2.10"

Because the ansible-galaxy collection init command does not create the meta/ directory, you must create it yourself, as well as the runtime.yml file.

From inside the collection directory, run the ansible-galaxy collection build command to prepare the collection:

[user@host mycollection]$ ansible-galaxy collection build
Created collection for mynamespace.mycollection at /home/user/mynamespace/mycollection/mynamespace-mycollection-1.0.0.tar.gz

You can use the resulting .tar.gz file to install and test the collection locally, to share the collection with team members, or to publish it to a distribution platform such as Ansible Galaxy or private automation hub.

When you publish your collection to Ansible Galaxy, automation hub, or private automation hub, the platforms automatically run some tests.

For example, private automation hub uses the ansible-lint tool to verify that your collection conforms to the standards and good practices that the Ansible team establishes. The distribution platform publishes the resulting report alongside the collection. The following output shows an import log for the mynamespace.mycollection collection.

Importing with galaxy-importer 0.4.4
Getting doc strings via ansible-doc
Finding content inside collection
Loading role myrole
Linting role myrole via ansible-lint...
roles/myrole/tasks/main.yml:3: fqcn-builtins Use FQCN for builtin actions.
roles/myrole/tasks/main.yml:3: risky-file-permissions File permissions unset or incorrect.
CHANGELOG.rst file not found at top level of collection.
Collection loading complete

Done

If the import log displays the messages Collection loading complete and Done, then the collection uploaded successfully. Notice that the log produces warnings about fqcn-builtins and risky-file-permissions. Although not required, you might update the collection to fix any reported problems.

If your collection does not include a CHANGELOG.rst file, then the import log displays the message: CHANGELOG.rst file not found at top level of collection. Because this file is not required, you can safely ignore this message. You can find information about generating change logs in the References section.

For collections that Red Hat partners develop, automation hub tests more thoroughly using the ansible-test tool.

The Ansible team recommends that you install and then use those tools before publishing your collections. In addition, some community projects also run those tools and reject contributions that do not pass the tests.

At a minimum, install your collection on a test system from the .tar.gz file, and then develop a playbook that uses the collection and demonstrates that it works as expected.