fqcn¶

此规则检查 Ansible 内容中的完全限定集合名称 (FQCN)。

声明 FQCN 可确保操作使用来自正确命名空间的代码。这避免了可能导致操作失败或产生意外结果的歧义和冲突。

fqcn 规则具有以下检查

fqcn[action] - 对模块操作使用 FQCN，例如 ...
fqcn[action-core] - 检查来自 ansible.legacy 或 ansible.builtin 集合的 FQCN。
fqcn[canonical] - 您应该使用规范的模块名称 ... 而不是 ...
fqcn[deep] - 检查集合内部的深层/嵌套插件目录。
fqcn[keyword] - 对于所有插件、模块、角色和 playbook，通过使用 FQCN 来避免 collections 关键字。

注意

在大多数情况下，您应该为内部 Ansible 操作声明 ansible.builtin 集合。如果使用带有操作的本地覆盖，例如 shell 模块，则应声明 ansible.legacy 集合。

警告

此规则不考虑 collections 关键字来解析内容。 collections 关键字提供了一种临时机制，用于过渡到 Ansible 2.9。您应该重写任何使用 collections: 键的内容，并尽可能避免使用它。

规范的模块名称¶

规范的模块名称也称为解析的模块名称，在大多数情况下应该优先使用。许多 Ansible 模块具有多个别名和重定向，因为这些是在内容重构时随着时间的推移创建的。尽管如此，它们最终都会解析为相同的模块名称，但这并非没有增加一些性能开销。由于一些非常旧的别名在某个时候会被删除，因此最好只是刷新内容，使其指向当前的规范名称。

使用规范名称的唯一例外是，如果您的代码仍然需要与非常旧版本的 Ansible 兼容，该版本不知道如何解析该名称。如果您发现自己处于这种情况，请随时将此规则添加到忽略列表中。

深层模块¶

编写模块时，应避免将其嵌套在深层目录中，即使 Ansible 允许您这样做。自 2023 年初以来，官方指导（由核心团队支持）是对模块使用扁平目录结构。这确保了最佳性能。

仍然使用深层目录的现有集合可以通过添加重定向来以向后兼容的方式迁移到扁平结构，例如在此示例中所示。

有问题的代码¶

---
- name: Example playbook
  hosts: all
  tasks:
    - name: Create an SSH connection
      shell: ssh ssh_user@{{ ansible_ssh_host }} # <- Does not use the FQCN for the shell module.

正确的代码¶

---
- name: Example playbook (1st solution)
  hosts: all
  tasks:
    - 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: all
  tasks:
    - name: Create an SSH connection
      # Use the FQCN for the builtin shell module.
      ansible.builtin.shell: ssh ssh_user@{{ ansible_ssh_host }}

注意

可以使用 --fix 选项自动修复此规则。