Upcoming canonical FQCN in Ansible

As we are working towards using canonical full-qualified collection name in Ansible, we need to check how many modules are using a deep structure as they will be affected by this change.

What is the canonical name?

The canonical module name is the name that is reported by ansible-doc --list and it represents the resolved full path of a module. Redirects are resolved and they are never reported as canonical name.

It should be noted that using canonical names is also notably faster than redirects, as resolving those takes time and multiple IO operations. These are also more stable, as redirects and aliases can be dropped at some point.

Proposed changes

We currently have PR #2604 in ansible-lint which will ask users to use canonical names instead of short names or aliases. This will be followed by documentation changes so we will be sure that documentation does expose the canonical name.

There is also a discussions topic under Ansible community about the canonical FQCN.

This will be followed by a change in documentation, so we will be sure that the exposed name is the canonical one and not the “root” level alias.

What is the impact?

It should be clear that this is not a breaking change, as it would only mean that we would recommend using another name from a list of names that are already allowed and continue to work. This change is more likely to be visual than anything else.

To assert the impact, I made a list with all collections that had a release during 2022 year (~1600), installed them (1.1GB) and checked for how many modules do expose a name with more than 2 dots (e.g. namespace.collection.module).

As of October 2022, 6% (908) of ~14000 modules are using a deep structure. Out of these 885 (97%) are under community namespace, making the “nesting” mostly mostly a community issue.

  • awcrosby.cisco_ios_test - 1 module
  • cisco.nxos.storage - 3 modules
  • community.general - 550 modules
  • community.network - 315 module
  • community.sap - 15 modules
  • haught.apcos - 10 modules
  • ibm.power_aix.internal - 1 module
  • mgdis.ovh - 13 modules

Basically, we have only 8 collections where the recommended canonical name will be a longer string. This will happen only if the maintainers of these collections do not decide to go do something about it.

What can be done?

Collection maintainers can decide to flatten the structure of their modules to ensure that the effective disk location also matches the desired canonical name. That would not be a breaking change as we already have support for redirects.

For collections that seem to have a really big number of modules, this might be the opportunity to split them into multiple collections. In case it is not already obvious, community.general and community.network are the two that should consider this option.

We can easily imagine how the 65 modules from within community.general.system. can be moved under community.system., which will ensure that their names are shorter and canonical at the same time.