fqcn¶

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 produceunexpected results.

Thefqcn rule has the following checks:

fqcn[action] - Use FQCN for module actions, such ...
fqcn[action-core] - Checks for FQCNs from theansible.legacy oransible.builtin collection.
fqcn[canonical] - You should use canonical module name ... instead of ...
fqcn[deep] - Checks for deep/nested plugins directory inside collections.
fqcn[keyword] - Avoidcollections keyword by using FQCN for all plugins, modules, roles and playbooks.

Note

In most cases you should declare theansible.builtin collection for internal Ansible actions.You should declare theansible.legacy collection if you use local overrides with actions, such with as theshell module.

Warning

This rule does not takecollections keyword into consideration for resolving content.Thecollections keyword provided a temporary mechanism transitioning to Ansible 2.9.You should rewrite any content that uses thecollections: key and avoid it where possible.

Canonical module names¶

Canonical module names are also known asresolved module names and they areto be preferred for most cases. Many Ansible modules have multiple aliases andredirects, 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 withoutadding 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 canonicalname.

The only exception for using a canonical name is if your code still needs to becompatible with a very old version of Ansible, one that does not know how toresolve that name. If you find yourself in such a situation, feel free to addthis rule to the ignored list.

Deep modules¶

When writing modules, you should avoid nesting them in deep directories, even ifAnsible allows you to do so. Since early 2023, the official guidance, backed bythe core team, is to use a flat directory structure for modules. This ensuresoptimal performance.

Existing collections that still use deep directories can migrate to the flatstructure in a backward-compatible way by adding redirects like inthis example.

Problematic Code¶

----name:Example playbookhosts:alltasks:-name:Create an SSH connectionshell:ssh ssh_user@{{ ansible_ssh_host }}# <- Does not use the FQCN for the shell module.

Correct Code¶

----name:Example playbook (1st solution)hosts:alltasks:-name:Create an SSH connection# Use the FQCN for the legacy shell module and allow local overrides.ansible.legacy.shell:ssh ssh_user@{{ ansible_ssh_host }} -o IdentityFile=path/to/my_rsa

----name:Example playbook (2nd solution)hosts:alltasks:-name:Create an SSH connection# Use the FQCN for the builtin shell module.ansible.builtin.shell:ssh ssh_user@{{ ansible_ssh_host }}