Using Fully-Qualified Collection Names (FQCN) in Ansible Content
In the world of automation and orchestration, Ansible has established itself as a popular choice for managing IT infrastructure and application deployments. Ansible allows you to create powerful automation scripts, or playbooks, to streamline tasks and manage resources efficiently. However, as with any coding or scripting language, adhering to best practices is essential for maintaining code quality and avoiding potential pitfalls. This article focuses on a specific Ansible linting rule called "fqcn," which checks for fully-qualified collection names (FQCN) in Ansible content.
What Is FQCN?
A Fully-Qualified Collection Name, or FQCN for short, is a way to specify the full namespace for an Ansible module or action. It serves the purpose of eliminating ambiguity and ensuring that the correct code from the correct collection is executed. In the context of Ansible, collections refer to reusable packages of playbooks, roles, modules, and other components that help streamline automation tasks.
The "fqcn" rule helps maintain code quality by ensuring that you use FQCNs for module actions. This rule offers several checks, including:
fqcn[action]: Encourages the use of FQCN for module actions.
fqcn[action-core]: Checks for FQCNs from theansible.legacyoransible.builtincollection.
fqcn[canonical]: Promotes the use of canonical module names over aliases or redirects.
fqcn[deep]: Discourages deep/nested plugins directories within collections.
fqcn[keyword]: Advises against using the "collections" keyword by using FQCN for all plugins, modules, roles, and playbooks.
Canonical Module Names
Canonical module names, also known as resolved module names, are the preferred way to refer to Ansible modules. Many Ansible modules have multiple aliases and redirects that were created over time as the content evolved. However, all these aliases eventually resolve to the same module name. By using canonical names, you can simplify your code and avoid performance overhead.
The only exception to using canonical names is when your code needs to be compatible with very old Ansible versions that do not recognize these names. In such cases, you can exclude this rule from the linter's checks.
Note: Ansible provides an option to automatically fix for a selection of modules for the "fqcn" error using the ansible-lint --fix option, which can be a helpful tool in resolving this issue in your playbooks.
Avoid Deep Modules
Starting in early 2023, the official guidance from Ansible's core team is to avoid nesting modules in deep directories. It's recommended to use a flat directory structure for modules, as it ensures optimal performance. Existing collections that use deep directories can migrate to the flat structure in a backward-compatible way by adding redirects.
Problematic Code and Correct Solutions
Let's look at some examples of problematic code and