Collections included in Ansible should not use files outside of meta/, plugins/, roles/ and playbooks/

[felixfontein]

Summary

This came up in #65 (comment). If we want to start excluding files from installed collections in the Ansible install, we should make sure (somehow) that these files are not needed by the collection.

I propose to extend the inclusion collection requirements to require that modules, plugins, roles and playbooks included in the collection (that are targetted at users) should not use any file from the collection except files in

1. meta/ (and these only indirectly, i.e. ansible-core loads them);
2. plugins/;
3. roles/;
4. playbooks/.

(I think playbooks can be launched by FQCN, that's why I added them here. I haven't used that feature so far, and I'm not sure if any collection in Ansible actually has such playbooks which are targetted for consumption by users, but since that feature exists we should not prevent collections from using it.)

As the first step, let's dicuss whether this makes sense. Afterwards, we can tackle a concrete formulation (assuming we can find some consensus for that) and finally vote on it.

Additional Information

No response

[acozine]

This seems like a timely, smart preventive measure that will help keep the Ansible package from getting bloated by extra files.

[jillr]

I think this list looks good. I've definitely seen collections (not currently in the Ansible package) that use things like samples/ or examples/ but those cases would be able to be moved to playbooks/ or roles/, so the use case is covered. I can't think of anything else that is missing.

[mariolenz]

Good idea. This would make it very easy to strip down Ansible by having a whitelist of files and directories to include instead of managing a list of things to exclude.

[sean-m-sullivan]

as a group that uses examples and playbooks, I still think this is a good idea. Examples in our case are made to be additional documentation, though I don't know how many users actually use those files. Its still good for the repo to have the, but don't need to be an ansible-core install, even though we likely will never be included in our current form

[mariolenz]

I've definitely seen collections (not currently in the Ansible package) that use things like samples/ or examples/ but those cases would be able to be moved to playbooks/ or roles/, so the use case is covered.

I don't agree. I should say that samples / examples are a kind of documentation and shouldn't go into playbooks/ or roles/.

Examples in our case are made to be additional documentation, though I don't know how many users actually use those files.

It's OT for this discussion, but should there be a guidance where to put examples? Collection directories and files doesn't know about an examples/ directory. Should there be one? Or should examples go into docs/examples/?

Or should examples go into the EXAMPLES in the module documentation? On the one hand, this makes sense to me. On the other hand, this wouldn't be the right place to provide more complex examples how something can be done by combining several modules.

Would it be worth to start a discussion on this? I don't know, just wanted to raise the question.

[felixfontein]

In playbooks/ and roles/ there should be collection content, not examples. Playbooks and roles included in collections can be executed by users once the collection is installed by referencing the FQCN.

@mariolenz I think it's worth to start a discussion on that. Feel free to create a discussion issue :)

[sean-m-sullivan]

@felixfontein this is the collection reference
https://github.com/redhat-cop/tower_configuration/
where we use example to chain Multiple Roles and modules together for the user. WE also have roles, modules, playbooks for execution. It is likely a seperate discussion. However the question is, should an examples folder used for documentation, be included in the ansible core for those collection maintainers that want to provide it to users, or is on their repo site enough.

I'm fine with it only being on our repo, as its not displayed in Automation hub/galaxy, and I very much doubt that users go into the collection install folder that deep to look for that documentation. its mostly the website and the galaxy/hub.

[felixfontein]

@sean-m-sullivan thanks for the link! BTW, when I looked at some of the roles, I noticed that they don't provide a role argument spec. It might be worth adding one, this also makes the roles discoverable with ansible-doc -t role -l.

and I very much doubt that users go into the collection install folder that deep to look for that documentation.

I fully agree! I expect users to use ansible-doc to view documentation, or use the repository, collection website/docsite, or other online resources.

(And collections included in the Ansible package are not even installed in regular collection installation directories, but in Python's site-packages, where even less people look around for docs :) )

[mariolenz]

@mariolenz I think it's worth to start a discussion on that. Feel free to create a discussion issue :)

I created #73 for this.

[felixfontein]

Closing since #77 has been completed, and the examples discussion is continued in #73. Thanks everyone!