How we should normalize FQCN names?

[ssbarnea]

As #2572 opened a serious of questions, I am trying to survey what users would expect to to use FQCN names.

All the options below are equivalent:

• sudoers (old name, not to be used)
• community.general.sudoers (location documented in metadata)
• community.general.system.sudoers (effective/resolved location)

Still, inside ansible-lint and with ansible-language-server, it can be only one suggestion, and we already know that the first option is not acceptable.

Few observations:

• The second one happens to the documented form.
• The second one can be an alias or a symlink pointing to the current location on disk
• The 3rd one can also be called "resolved" location, which basically points to the current implementation on disk
• Modules moved and will continue to move, usually inside a collection but sometimes even into a new collection.
• We would expect for the documentation to expose the normalized/recommended form at least, so whatever decision we make, we should look to ensure that the built documentation page of the module does make use of it.
• The 3rd option (resolved), is expected to be (measurably) faster as it would not involved lots of filesystem browsing in order to find the implementation.
• A module can have multiple aliases pointing to it and we already have several cases like that. Still they can always have only one resolved name.

[cidrblock]

After a quick review of a couple example docs: https://docs.ansible.com/ansible/latest/collections/community/general/sudoers_module.html

This plugin believes it's name is "community.general.sudoers" as shown in the examples. To avoid confusion and varied use, IMHO standardizing on a 3 part name, and leaving symlinks and collection specific internal directory structures as non-user facing implementation details feels sane.

[ssbarnea]

Apparently @bcoca reports that the resolving performance penalty is quite serious. Also, I have no clear idea how can I determine which alias would be considered the reference one when multiple are active.

Maybe we should just require collection authors to advertise the resolved module location in their documentation, so people would go for the newest and fastest location, especially as copy/paste is easy.

[ssbarnea]

New findings...

# List available 
$ ansible-doc -l|grep sudoers
community.general.system.sudoers                                                    Manage sudo...

# List available plugins
$ ansible-doc -F|grep sudoers
community.general.system.sudoers                                                    /Users/ssbarnea/.ansible/collections/ansible_collections/community/general/plugins/modules/system/sudoers.py

$ ansible-doc community.general.system.sudoers|head -1
> COMMUNITY.GENERAL.SUDOERS    (/Users/ssbarnea/.ansible/collections/ansible_collections/community/general/plugins/modules/system/sudoers.py)

The reality is that the docstring of the plugin only has its short name inside.

This makes me believe that there is a bug in the function that is producing the fully qualified name, which is also why the documentation advertises COMMUNITY.GENERAL.SUDOERS instead of community.general.system.sudoers.

Also the listing from current (old) galaxy shows the resolved names, like https://galaxy.ansible.com/community/general -- content will show system.sudoers instead of just sudoers.

There is also core own redirects, which were not updated since June 2021 at https://github.com/ansible/ansible/blob/devel/lib/ansible/config/ansible_builtin_runtime.yml and they all point to flatmapping, basically because at that point in time that was where the code was. I doubt they have plans to maintain this list.

See also: ansible-community/community-topics#147

[cidrblock]

I should also note, the requirement for 3 part names should be limited to the production profile.

[bcoca]

FYI, the current ALL CAPS header should only appear when listing multiple entries ansible-doc copy template (long standing bug)

[felixfontein]

Please note that the second one (community.general.sudoers) is the only official form that community.general documents and supports. The third one (community.general.system.sudoers) is an implementation detail of flat-mapping and can change at any time. Relying on it is dangerous and should be avoided at all costs.

[felixfontein]

Since anslble-core's collection loader / redirection handling code treats symlinks the same as regular files, I don't think that's really needed.

[bcoca]

no, they are treated as aliases, they used to be treated as 'cannonical' ,why c.general worked with 2.9 via symlinks, but now they are properly followed, but not considered the canonical name. Listing ignores aliases to avoid showing dupes.

[felixfontein]

But that's only for listing modules? At least I couldn't find any symlink check in the redirect handling code, and also didn't see any redirect comments on higher verbosity levels.

[bcoca]

well, in loading the one doing the redirect is the filesystem and all aliases (no matter how they are defined) should still load the correct plugin.

[ssbarnea]

I still remember that official guidelines for finding a module you could use was to use "ansible-doc --list | grep foo. The reality is that both -land-F` return only the canonical (resolved) forms only and they will likely never list aliases.

That guideline is even part of EX447 certification exam, as I still remember when I took the exam. You are not expected to know all modules, but your are expected to know how to find them and their documentation from the command line. What it displayed as canonical name depends on each collection implementation, so neither the linter or vscode extension will impose one form, but it will use the only name that is 100% known to exist, the canonical one. Aliases (this includes symlinks) can vary in time, as they can also be removed not only added.

I hope that we can fix the ALL-CAPS name sooner as it only confuses user as it diverge from the canonical name.

If anyone questions the preference for canonical, they should consider the fact that this was the only consistent way of loading a module, the others has different behaviors between versions, being more of backwards-compatibility transitional hacks. If user never moves the call to canonical, we can see cases where there are 30 redirections until the file is (potentially) found on disk. And yep, creating loops by mistake is something that could happen. These do come with notable performance degradation, something that canonical form is not affected by.

[felixfontein]

I still remember that official guidelines for finding a module you could use was to use ansible-doc --list | grep foo.

I've never seen or heard about that being an official guideline before, but then I also didn't take any Ansible exams :) I guess then it's even more urgent to get rid of the nested directory structure in c.g and c.n as soon as possible.

[bluikko]

• community.general.system.sudoers (effective/resolved location)

There should be no controversy as c.g has stated that this will not be usable in the future and was never even supposed to be visible.
It should be the normal 3-part FQCN.