Ansible troubleshooting - Error fqcn

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 the ansible.legacy or ansible.builtin collection.
• 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 how to correct them:

Problematic Code

---
- name: Example playbook
  hosts: all
  tasks:
    - name: Create an SSH connection
      shell: ssh ssh_user@{{ ansible_ssh_host }}

The above code does not use FQCN for the shell module.

Output

WARNING  Listing 3 violation(s) that are fatal
command-instead-of-shell: Use shell only when shell functionality is required.
fqcn.yml:5 Task/Handler: Create an SSH connection

fqcn[action-core]: Use FQCN for builtin module actions (shell).
fqcn.yml:5 Use `ansible.builtin.shell` or `ansible.legacy.shell` instead.

no-changed-when: Commands should not change things if nothing needs doing.
fqcn.yml:5 Task/Handler: Create an SSH connection

Read documentation for instructions on how to ignore specific rule violations.

                        Rule Violation Summary                        
 count tag                      profile    rule associated tags       
     1 command-instead-of-shell basic      command-shell, idiom       
     1 no-changed-when          shared     command-shell, idempotency 
     1 fqcn[action-core]        production formatting                 

Failed: 3 failure(s), 0 warning(s) on 1 files. Last profile that met the validation criteria was 'min'.

Correct Code (1st Solution)

---
- name: Example playbook (1st solution)
  hosts: all
  tasks:
    - name: Create an SSH connection
      ansible.legacy.shell:
        ssh ssh_user@{{ ansible_ssh_host }} -o IdentityFile=path/to/my_rsa

In this solution, the FQCN for the legacy shell module is used, allowing local overrides.

Correct Code (2nd Solution)

---
- name: Example playbook (2nd solution)
  hosts: all
  tasks:
    - name: Create an SSH connection
      ansible.builtin.shell: ssh ssh_user@{{ ansible_ssh_host }}

This solution uses the FQCN for the builtin shell module.

By using FQCNs, you ensure that your code references the correct collection and module, reducing the chances of ambiguity and conflicts.

Conclusion

The “fqcn” Ansible linting rule is a valuable tool for ensuring code quality in your Ansible content. By adhering to FQCN best practices, you can prevent potential issues and maintain consistent and efficient automation scripts. Following Ansible’s recommended guidelines for using canonical module names and avoiding deep module directories can help you write cleaner, more performant automation code.

Academy

Learn the Ansible automation technology with some real-life examples in my Udemy 300+ Lessons Video Course.

My book Ansible By Examples: 200+ Automation Examples For Linux and Windows System Administrator and DevOps

Donate

Want to keep this project going? Please donate

Patreon Buy me a Pizza