Directory structure / module naming

[felixfontein]

SUMMARY

In ansible/ansible, the crypto modules were organized in a directory structure. Most modules were in the root, but the ACME and ECS modules were in subdirectories.

In collections, this is no longer the case (except for community.general, which uses a technique called flatmapping which isn't fully supported yet, hence "some" symlinks). Right now, our modules are all in one directory, plugins/modules/.

Having subdirectories means that the fully qualified collection names (FQCNs) get longer. For example, if we would have the same subdirectories as in ansible/ansible, the acme_certificate module would have to be accessed via community.crypto.acme.acme_certificate, instead of the current community.crypto.acme_certificate. But at the same time, we could also adjust the module names, like rename acme_certificate to certificate. Then the FQCN would be community.crypto.acme.certificate. (We'd have to adjust Ansible's routing.yml afterwards so that playbooks which worked with Ansible 2.9 continue to work with Ansible 2.10 ACD.)

Also we could use this chance to move x509_* into a subdirectory x509/, and also move openssl_certificate into there (so we'd have community.crypto.x509.certificate instead of community.crypto.openssl_certificate).

Doing this renames opens up some potential pitfalls though (what mostly comes up to my mind is docs generation):

1. Multiple modules will be called certificate (acme.certificate, ecs.certificate, and maybe also x509.certificate). That shouldn't be a problem in itself, but might confuse docs generation.
2. More on docs generation: when linking to other module docs with M(...), this might not work well when subdirectories are involved.

Any opinions on directory structure, renames, and potential problems (the potential docs problems as well as other potential problems)?

I'd say it's best to decide on this soon, so we can rename everything (and adjust Ansible's routing.yml) before the first proper release of this collection, and before Ansible 2.10 is released.

CC @ctrufan @MarkusTeufelberger @puiterwijk @Shaps @Spredzy @Xyon, and also @gundalow @abadger

ISSUE TYPE

• Feature Idea

COMPONENT NAME

[abadger]

I don't think this was anticipated. If any class of plugin within a collection had non unique names, i think it will cause issues which the core team may not have any interest in resolving. I think we'd need to break the plugins up into seperate collections if you want to have duplicated names

…

On Sun, Mar 22, 2020, 10:39 AM Felix Fontein ***@***.***> wrote: SUMMARY In ansible/ansible, the crypto modules were organized in a directory structure <https://github.com/ansible/ansible/tree/stable-2.9/lib/ansible/modules/crypto/>. Most modules were in the root, but the ACME and ECS modules were in subdirectories. In collections, this is no longer the case (except for community.general, which uses a technique called flatmapping which isn't fully supported yet, hence "some" symlinks <https://github.com/ansible-collections/community.general/tree/master/plugins/modules/>). Right now, our modules are all in one directory, plugins/modules/ <https://github.com/ansible-collections/community.crypto/tree/master/plugins/modules> . Having subdirectories means that the fully qualified collection names (FQCNs) get longer. For example, if we would have the same subdirectories as in ansible/ansible, the acme_certificate module would have to be accessed via community.crypto.acme.acme_certificate, instead of the current community.crypto.acme_certificate. But at the same time, we could also adjust the module names, like rename acme_certificate to certificate. Then the FQCN would be community.crypto.acme.certificate. (We'd have to adjust Ansible's routing.yml <https://github.com/ansible/ansible/blob/temp-2.10-devel/lib/ansible/config/routing.yml#L3290-L3291> afterwards so that playbooks which worked with Ansible 2.9 continue to work with Ansible 2.10 ACD.) Also we could use this chance to move x509_* into a subdirectory x509/, and also move openssl_certificate into there (so we'd have community.crypto.x509.certificate instead of community.crypto.openssl_certificate). Doing this renames opens up some potential pitfalls though (what mostly comes up to my mind is docs generation): 1. Multiple modules will be called certificate (acme.certificate, ecs.certificate, and maybe also x509.certificate). That shouldn't be a problem in itself, but might confuse docs generation. 2. More on docs generation: when linking to other module docs with M(...), this might not work well when subdirectories are involved. Any opinions on directory structure, renames, and potential problems (the potential docs problems as well as other potential problems)? I'd say it's best to decide on this soon, so we can rename everything (and adjust Ansible's routing.yml) before the first proper release of this collection, and before Ansible 2.10 is released. CC @ctrufan <https://github.com/ctrufan> @MarkusTeufelberger <https://github.com/MarkusTeufelberger> @puiterwijk <https://github.com/puiterwijk> @Shaps <https://github.com/Shaps> @Spredzy <https://github.com/Spredzy> @Xyon <https://github.com/Xyon>, and also @gundalow <https://github.com/gundalow> @abadger <https://github.com/abadger> ISSUE TYPE - Feature Idea COMPONENT NAME - — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#3>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AABTCWVGNGC3LMUXPGFR4ZTRIZEMBANCNFSM4LRL4GIA> .

[felixfontein]

Ok, in that case, I guess the only option of interest is flatmapping, i.e. similarly to community.general we use subdirectories, which are ignored by Ansible. (And since that doesn't work with 2.9, and not yet with 2.10.devel, symlinks are needed like in community.general.)

Any opinions on this @ctrufan @MarkusTeufelberger @puiterwijk @Shaps @Spredzy @Xyon?

Otherwise it's probably best to stay with the current structure, then...

[ctrufan]

No strong opinions here - it sounds like sticking with the current structure is the best approach for now? I don't think it makes sense to split up things like acme/ecs into separate collections, especially given their dependency on the rest of community.crypto.

[MarkusTeufelberger]

For duplicate names, we could turn the structure upside down too (community.crypto.certificate.x509, community.crypto.certificate.openssh, community.crypto.certificate.acme etc), I don't think that's a great move either though and would lead to issues in the opposite way (community.crypto.keypair.x509, community.crypto.keypair.openssh...)

Personally I'm fine with just keeping the _ in the name and a flat folder for all modules, since Ansible core seems not to be equipped or willing to deal with this. I also think all crypto modules should stay in here (at most I would rename the repository itself to crypto, just like the kubernetes one). The alternative would be a handful of collections (crypto.common, crypto.x509, crypto.openssh etc.) with no clear benefit other than having a dot instead of an underscore.

If we grow to ~50+ modules, I'd revisit this, but for now I find the current structure ok.

Another more practical issue would be that a module name that's just "certificate" in a role/play might not be as clear to a reader compared to "x509_certificate" or "acme_certificate" or "openssh_certificate".

[felixfontein]

@MarkusTeufelberger I definitely dislike certificate.x509 ;-) Also, I like your argument on x509_certificate being better than certificate.

And I don't like having random more collections at all. This only makes sharing code more complicated (we'd need crypto.common then, +1 more collection haha) and the requirements files longer/more complex for users.

I'm for keeping the current structure. (Except renaming openssl_certificate to x509_certificate, but that's another topic ;) )

[Shaps]

I'm with @MarkusTeufelberger on this, We don't have enough modules (per sub-type) to justify splitting this into separate directories/FQCNs. If the per-sub-type amount of modules grows, I'd be more keen on having crypto.<sub-type>.

[felixfontein]

Ok, in that case we keep the current structure :)

BTW, CI is now working! So freel free to create PRs if you have something you want to improve, fix, extend, ...!