This rule checks for fully-qualified collection names (FQCN) in Ansible content.
Declaring an FQCN ensures that an action uses code from the correct namespace. This avoids ambiguity and conflicts that can cause operations to fail or produce unexpected results.
fqcn rule has the following checks:
fqcn[action]- Use FQCN for module actions, such ...
fqcn[action-core]- Checks for FQCNs from the
fqcn[canonical]- You should use canonical module name ... instead of ...
fqcn[deep]- Checks for deep/nested plugins directory inside collections.
collectionskeyword by using FQCN for all plugins, modules, roles and playbooks.
In most cases you should declare the
ansible.builtin collection for internal Ansible actions.
You should declare the
ansible.legacy collection if you use local overrides with actions, such with as the
This rule does not take
collections keyword into consideration for resolving content.
collections keyword provided a temporary mechanism transitioning to Ansible 2.9.
You should rewrite any content that uses the
collections: key and avoid it where possible.
Canonical module names¶
Canonical module names are also known as resolved module names and they are to be preferred for most cases. Many Ansible modules have multiple aliases and redirects, as these were created over time while the content was refactored. Still, all of them do finally resolve to the same module name, but not without adding some performance overhead. As very old aliases are at some point removed, it makes to just refresh the content to make it point to the current canonical name.
The only exception for using a canonical name is if your code still needs to be compatible with a very old version of Ansible, one that does not know how to resolve that name. If you find yourself in such a situation, feel free to add this rule to the ignored list.
When writing modules, you should avoid nesting them in deep directories, even if Ansible allows you to do so. Since early 2023, the official guidance, backed by the core team, is to use a flat directory structure for modules. This ensures optimal performance.
Existing collections that still use deep directories can migrate to the flat structure in a backward-compatible way by adding redirects like in this example.
This rule can be automatically fixed using