Ansible collection creator path
If you are unfamiliar with Ansible collections, first take a look at the Using Ansible collections guide.
Ansible collections are a distribution format for Ansible content that can include playbooks, roles, modules, and plugins.
A typical collection addresses a set of related use cases. For example, the
community.dns collection includes modules and plugins to work with DNS.
You can install collections made by others or share yours with the community through a distribution server such as Ansible Galaxy. Certified collections can be published to the Red Hat Automation Hub, a part of the Red Hat Ansible Automation Platform.
Creating and sharing collections is a great way of contributing to the Ansible project.
The Ansible community package consists of
ansible-core, which, among other core components, includes the
ansible.builtin collection maintained by the Core team, and a set of collections maintained by the community.
The purpose of this guide is to give you as a (potential) content creator a consistent overview of the Ansible collection creator journey from an idea for the first module/role to having your collection included in the Ansible community package. The Collection development guidelines section provides references to more detailed aspects of this journey. The overall journey consists of the following milestones:
If you have an idea for a new role or module/plugin, there is no need to reinvent the wheel if there is already a sufficient solution that solves your automation issue.
Therefore, first examine the currently available content including:
Ansible Automation Hub if you have the Ansible Automation Platform subscription
In case the solutions you found are not fully sufficient or have flaws, consider improving them rather than creating your own. Each collection includes information on where to create issues for that collection to propose your enhancement ideas.
If you already have your content written and used in your workflows, you can still consider integrating it to the existing solutions. However, if these options do not apply to your collection ideas, we encourage you to create and share your own.
You tried but have not found any sufficient solution for your automation issue.
Use one of the following guides:
You created new content.
Now it is time to create a reusable and sharable collection. Use the Developing collections guide to learn how.
We recommend you to use the collection_template repository as a basis for your collection.
README.md file should contain a quick-start installation and usage guides.
You can use the community.general collection README file as an example.
Publish your collection on a platform for software development and version control such as GitHub.
Make sure your collection contains exhaustive license information. Ansible is an open source project, so we encourage you to license it under one of open source licenses. If you plan to submit your collection for inclusion in the Ansible community package, your collection must satisfy the licensing requirements.
If you have used the collection_template repository we recommended earlier as a skeleton for your collection, it already contains the
GNU GPL v3 license.
When releasing new versions of your collections, take the following recommended practices into consideration:
This section is applicable to collections containing modules and plugins.
For role testing, see the Ansible Molecule project.
Testing your collection ensures that your code works well and integrates with other components such as
Take a look at the following documents:
Now make sure when pull requests are created in your collection repository they are automatically tested using a CI tool such as GitHub Actions or Azure Pipelines.
See the collection_template/README.md as an example.
To distribute your collection and allow others to conveniently use it, publish your collection on one or more distribution servers. See the Distributing collections guide to learn how.
Make you collection satisfy the Ansible community package collections requirements and submit it for inclusion. See the inclusion process description to learn how.
Maintain your collection. See the Ansible collection maintainer guidelines for details.
Engage with the community. Take a look at the Ansible communication guide to see available communication options.
- Developing collections
A set of guidelines about collection development aspects