使用Ansible Collection时自定义Filter插件无法识别的问题

问题背景 #

你在Collection的t1角色内放置了filter_plugins/filter.py，本地运行角色时插件正常工作，但将Collection通过requirements.yaml安装到外部仓库后，调用角色时出现Filter插件找不到的错误：

fatal: [localhost]: FAILED! => {"msg": "template error while templating string: Could not load \"something\": 'something'. String: {{ 'this is a message' | something }}. Could not load \"something\": 'something'"}

解决方案 #

方案一：迁移插件到Collection级别的插件目录（推荐） #

Ansible官方规范中，Collection的插件应该放在根目录的plugins/[plugin_type]目录下，这样安装后Ansible会自动加载这些插件，无需额外配置。

操作步骤：

1. 在Collection根目录创建plugins/filter目录：

mkdir -p plugins/filter

2. 将角色内的roles/t1/filter_plugins/filter.py移动到plugins/filter/目录下（文件名可自定义，比如something_filter.py）
3. 重新推送你的Collection仓库，然后在外部仓库重新安装：

ansible-galaxy collection install -r requirements.yaml -p ./collections --force

再次运行剧本即可正常识别Filter插件。

方案二：保留插件在角色内，显式指定插件路径 #

如果不想迁移插件，可在调用角色的剧本中，通过变量指定Filter插件的路径：

---
- name: demo
  hosts: localhost
  connection: local
  become: false
  vars:
    # 动态获取Collection的安装路径，指向角色内的filter_plugins目录
    filter_plugins: "{{ lookup('ansible.builtin.collection_dir', 'platform.test') }}/roles/t1/filter_plugins"
  roles:
  - role: platform.test.t1

注意：这种方式依赖Collection的安装路径，灵活性不如方案一，仅适用于特殊场景。

原因说明 #

本地运行时，Ansible会自动扫描当前工作目录下角色内的filter_plugins目录；但当Collection被安装到独立目录后，Ansible默认只会加载Collection根目录plugins/下的各类插件，不会自动遍历角色内部的插件目录，因此需要通过规范目录结构或显式指定路径来解决。

内容的提问来源于stack exchange，提问作者soapdish