docs: clarification about modules prefixes in collections

[resmo]

Because of FQCN, developers could think of shorten the module name:

vultr_server -> ngine_io.vultr.server vs. ngine_io.vultr.vultr_server

I see pro and cons for having or omitting the prefix. What is the recommendation?

Omiting a prefix:

Pro:

• Technically no need for a prefix unless another module in the collection has the same name (e.g. in community.general)
• Looks simpler, shorter FQCN

Cons:

• Higher risk to have identical names in different collections, forces use of FQCN in case of a collision
• Looking at the task using a module without a FQCN, it may not be clear what module is used (e.g. for cloud modules, every cloud may have a server module)

I tend to recommend module prefixes.

[felixfontein]

I think the OpenStack collection was thinking about removing prefixes (and there was an associated discussion about it). I don't remember where that discussion happened, though. Maybe @gundalow remembers more?

Anyway, two things to consider:

1. Having multiple modules of the same short name in the same collection (in different directories) will probably not work, and will not be supported by core. (Directory structure / module naming community.crypto#3) That's not what this question is about, but it is a related question :)
2. It is possible to add aliases, like name the module server, but make a symlink vultr_server.py→server.py. Then when using collection: ngine_io.vultr, you can use both server and vultr_server to reference this module. This makes it potentially more confusing if used wrong, but can make it a lot clearer if used right.

I'm currently tending to not do any tricks such as 2., and also stick to module prefixes. That avoids the various pitfalls of these tricks, even though you have to type a bit more. (But maybe there are more good arguments for short names I haven't heard yet...)

[resmo]

This just crosses my mind:

having a module with FQCN ngine_io.vultr.server: what if ansible would support (does it?) to resolve the module not just with server or ngine_io.vultr.server but also vultr.server. This may be qualified enough in many cases and a collision is less likely

[tremble]

For what it's worth I'm in favour of removing the prefixes. We already have the FQCN when you're trying to avoid ambiguity. We might want to encourage people to use FQCNs when publishing roles+playbooks which depend on other collections..

The OpenStack patch is https://review.opendev.org/#/c/713056/

I believe @emonty still intends to put this through (last time I spoke to him he was delaying because I had a batch of new modules in-flight). One of the main reasons we don't have something like this in-flight on the AWS side is that it's extra work that no-one with time has stepped up to address.

From IRC conversations I believe core would currently priorities module based on "collections" being defined, but that the scoping of this may be a little funky.

[sshnaidm]

I think the purpose of prefixes was intention not to confuse modules with same name like modules server or user in various cloud providers. Using prefixes inside one collection doesn't make much sense, so I think it will go away in some point. The problem is when using a few collections and core modules together (core module has user as well). Without FQCN it may be easy confused which exactly module should run in a particular case.
For example:

- hosts: all
  collections:
    - openstack
    - other_cloud
  tasks:
    - user:
        name: my_user

In this case not really clear which user will be created - system user, openstack user or other_cloud user?

[bcoca]

Openstack user, since collections keyword establishes precedence.

[bcoca]

Since you can have aliases, both names are possible. To start I recommend keeping the prefix for a while and deprecate once users get used to collections.

…

On Mon, Apr 6, 2020, 03:06 René Moser ***@***.***> wrote: Because of FQCN, developers could think of shorten the module name: vultr_server -> ngine_io.vultr.server vs. ngine_io.vultr.vultr_server I see pro and cons for having or omitting the prefix. What is the recommendation? Omiting a prefix: Pro: - Technically no need for a prefix unless another module in the collection has the same name (e.g. in community.general) - Looks simpler, shorter FQCN Cons: - Higher risk to have identical names in different collections, forces use of FQCN in case of a collision - Looking at the task using a module without a FQCN, it may not be clear what module is used (e.g. for cloud modules, every cloud may have a server module) — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <https://github.com/ansible-collections/overview/issues/42>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAGMES2323445A37VO6GF3DRLF5QPANCNFSM4MCAR3NA> .

[emonty]

Because there is an ansible builtin "user" I think we're going to change os_user to keystone_user for that reason.

That said, if:

- hosts: all
  collections:
    - openstack
    - other_cloud
  tasks:
    - user:
        name: my_user

is confusing to the person writing the playbook, they can either note the precedence role from @bcoca or they can just not add the new collections keyword which is new and fancy anyway.

- hosts: all
  tasks:
    - openstack.cloud.user:
        name: my_user

is unambiguous.

@bcoca - I was told the symlink alias trick didn't work anymore, so I assume the new alias mechanism is to just list something in the collection's routing.yml twice?

[emonty]

FTR: https://review.opendev.org/#/c/713056/ is the change to rename things (I need to fix it up and do a few more renames based on suggestions) and ansible/ansible#68215 is the ansible-side one (needs to be rebased and then updated once we update the openstack one)

Which is to say - I'm definitely in favor of suggesting removing the prefixes. openstack.cloud.os_server and ngine_io.vultr.vultr_server just look silly. openstack.cloud.server and ngine_io.vultr.server are much nicer.

[bcoca]

Symlinks work, but routing.tml is the intended 'feature' for aliases, the underscore as deprecation is what does not work at all in collections. The symlinks will work now and in 2.9, for routing, we are still waiting for the PR.