ansible-documentation
ansible-documentation copied to clipboard
ansible
Improve meta/main.yml documentation for roles
We mention the role structure and some specific portions of meta/main.yml in https://docs.ansible.com/ansible/latest/galaxy/user_guide.html#using-meta-main-yml but we don't define the whole thing anywhere in docs.
The specifc trigger for this issue is a user getting an ansible-lint error of :
meta-no-info: Role info should contain platforms
...and had no way to find out what this platforms section is about. In general, would be good to have a well-defined example of this in the docs.
Perhaps an extension of https://github.com/ansible/ansible/blob/devel/lib/ansible/galaxy/data/apb/meta/main.yml.j2
This forum topic may have some helpful information as well - https://forum.ansible.com/t/role-meta-data-platform-key-broken/4651
It mentions an old galaxy api page which can be reached at https://old-galaxy.ansible.com/api/v1/platforms/
...continuing the linkfest of places that might have the details needed - https://github.com/ansible/ansible-lint/blob/main/src/ansiblelint/schemas/meta.json
Discussed in DaWGs meeting: In general, ansible-lint is specific to Galaxy and may not be the definitive list we want to use in the general ansible docs.
I removed the platforms: blocks from the ansible-core role templates, since the URL documenting the choices is no longer there.
Not sure if this has been discussed elsewhere, but the related forum post appears to be about roles in collections, not standalone roles, and I'm not sure Galaxy and ansible-lint are in alignment on that (beyond Galaxy calling ansible-lint). I don't think a role in a collection can set a custom namespace or role_name in the galaxy_info of a role it contains for example, but a standalone role can change how it's imported in Galaxy by setting those fields. Maybe it's worth mentioning that caveat for collections in https://docs.ansible.com/ansible/latest/galaxy/user_guide.html#using-meta-main-yml, since all the templates contain galaxy_info because they were created for standalone roles.
I did find a very brief mention of the meta/main.yml here https://ansible.readthedocs.io/projects/galaxy-ng/en/latest/community/userguide/#changing-the-role-name (pretty sure it's role_name though).
