Creating collections

To create a collection:

Create a collection skeleton with the ansible-galaxy collection init command.
Add modules and other content to the collection.
Build the collection into a collection artifact with ansible-galaxy collection build.
Publish the collection artifact to Galaxy with ansible-galaxy collection publish.

A user can then install your collection on their systems.

Naming your collection 

Collection names consist of a namespace and a name, separated by a period (.). Both namespace and name should be valid Python identifiers. This means that they should consist of ASCII letters, digits, and underscores.

Note

Usually namespaces and names use lower-case letters, digits, and underscores, but no upper-case letters.

You should make sure that the namespace you use is not registered by someone else by checking on Ansible Galaxy’s namespace list. If you chose a namespace or even a full collection name that collides with another collection on Galaxy, it can happen that if you or someone else runs ansible-galaxy collection install with your collection name, you end up with another collection. Even if the namespace currently does not exist, it could be created later by someone else.

If you want to request a new namespace on Ansible Galaxy, create an issue on github.com/ansible/galaxy.

There are a few special namespaces:

ansible:: The ansible namespace is owned by Red Hat and reserved for official Ansible collections. Two special members are the synthetic ansible.builtin and ansible.legacy collections. These cannot be found on Ansible Galaxy, but are built-in into ansible-core.
community:: The community namespace is owned by the Ansible community. Collections from this namespace generally live in the GitHub ansible-collection organization. If you want to create a collection in this namespace, request it on the forum.
local:: The local namespace does not contain any collection on Ansible Galaxy, and the intention is that this will never change. You can use the local namespace for collections that are locally on your machine or locally in your Git repositories, without having to fear collisions with actually existing collections on Ansible Galaxy.

Creating a collection skeleton 

Create your collection skeleton in a path that includes ansible_collections, for example collections/ansible_collections/.

To start a new collection, run the following command in your collections directory:

ansible_collections#> ansible-galaxy collection init my_namespace.my_collection

Note

Both the namespace and collection names use the same strict set of requirements. See Galaxy namespaces on the Galaxy docsite for those requirements.

It will create the structure [my_namespace]/[my_collection]/[collection skeleton].

Hint

If Git is used for version control, the corresponding repository should be initialized in the collection directory.

Once the skeleton exists, you can populate the directories with the content you want inside the collection. See ansible-collections GitHub Org to get a better idea of what you can place inside a collection.

Reference: the ansible-galaxy collection command

Currently the ansible-galaxy collection command implements the following sub commands:

init: Create a basic collection skeleton based on the default template included with Ansible or your own template.
build: Create a collection artifact that can be uploaded to Galaxy or your own repository.
publish: Publish a built collection artifact to Galaxy.
install: Install one or more collections.

To learn more about the ansible-galaxy command-line tool, see the ansible-galaxy man page.