+

Search Tips   |   Advanced Search

Creating a new collection

Starting with Ansible 2.10, related modules should be developed in a collection. The Ansible core team and community compiled these module development tips and tricks to help companies developing Ansible modules for their products and users developing Ansible modules for third-party products. See Developing collections for a more detailed description of the collections format and additional development guidelines.

LICENSING REQUIREMENTS Ansible enforces the following licensing requirements:


Before you start coding

This list of prerequisites is designed to help ensure that you develop high-quality modules that work well with ansible-base and provide a seamless user experience.


Naming conventions

Fully Qualified Collection Names (FQCNs) for plugins and modules include three elements:

  • the Galaxy namespace, which generally represents the company or group

  • the collection name, which generally represents the product or OS
  • the plugin or module name

    • always in lower case

    • words separated with an underscore (_) character

    • singular, rather than plural, for example, command not commands

For example, community.mongodb.mongodb_linux or cisco.meraki.meraki_device.

It is convenient if the organization and repository names on GitHub (or elsewhere) match your namespace and collection names on Ansible Galaxy, but it is not required. The plugin names you select, however, are always the same in your code repository and in your collection artifact on Galaxy.


Speak to us

Circulating your ideas before coding helps you adopt good practices and avoid common mistakes. After reading the 'Before you start coding' section you should have a reasonable idea of the structure of your modules. Write a list of your proposed plugin and/or module names, with a short description of what each one does. Circulate that list on IRC or a mailing list so the Ansible community can review your ideas for consistency and familiarity. Names and functionality that are consistent, predictable, and familiar make your collection easier to use.


Where to get support

Ansible has a thriving and knowledgeable community of module developers that is a great resource for getting your questions answered.

In the Ansible Community Guide you can find how to:


Required files

Your collection should include the following files to be usable:

When you have these files ready, review the Contributing your module to an existing Ansible collection again. If you are creating a new collection, you are responsible for all procedures related to your repository, including setting rules for contributions, finding reviewers, and testing and maintaining the code in your collection.

If you need help or advice, consider join the #ansible-devel IRC channel (see how in the 'Where to get support').


New to git or GitHub

We realize this may be your first use of Git or GitHub. The following guides may be of use:

Next Previous