Preparation for Converting Your Role to the Collections Format
If you are developing a role in linux-system-roles, you may find your question already answered here.
Module and Module_utils Name
Q: My role has a custom module in the
library/ directory. Are there anything I should know of?
A: All of the files in the
library/ directory should have a
YOUR_ROLENAME_ prefix. For instance, if you are planning to name your module
getinfo, please name it
YOUR_ROLENAME_getinfo. This will help preventing the module name conflict when your role is converted to the collections format. In the format, all the modules are placed in the same directory
ansible_collections/NAMESPACE/COLLECTION_NAME/plugins/modules/, where popular names could get conflicted.
Q: How about module_utils?
module_utils/ directory in the collections format is allowed to have sub-directories. Please put all the files in your
module_utils/ directory in the
Q: What is the problem that you are trying to solve?
A: With collections, all of our modules are part of the public API - users can use them directly e.g.
fedora.system_roles.blivet:. There is currently no mechanism in Ansible to make these private (although Thomas Woerner has asked Ansible to provide this), and there is currently no convention to denote such modules as “private” e.g. use “_” as the first character in the module name (and a convention won’t prevent usage anyway).
With collections, the user can use the collections: keyword, and we’re back to global namespace collisions:
collections: - somenamespace.somename - fedora.system_roles ... - name: use blivet blivet: ...
This will use somenamespace.somename.blivet instead of the one from system roles. Although we can strongly recommend that users always use the FQCN fedora.system_roles.blivet we cannot guarantee that they will.
Q: Why not use a
YOUR_ROLENAME subdir under library/ ?
A: Because it is not currently supported by galaxy.
Q: Why not use a
YOUR_ROLENAME_ prefix for module_utils file? Why use a subdir?
A: Ease of conversion - the sub-directory style module_utils have been used in multiple roles and guaranteed to work.
Q: My role contains a sub-role. Are there any guidance for the sub-role naming?
A: A sub-role in a linux system role is completely private to the role. Thus, there is no restriction in naming. But now we have to consider how they are converted to the collections format. In short, the sub-role is promoted to the same level as the parent role is. The sub-role becomes reusable by the roles other than the original parent role in the collections format. But at the same time, it increases the risk of the naming conflict with the sub-roles from the other roles if the naming is too generic. We strongly recommend to name the sub-role name to be clear enough to reduce the risk. Although this is an imaginary example, if your main role is
rsyslog and it has a sub-role named
relp, it should be named
rsyslog_relp which is more descriptive and less chance to conflict.