如何为单个Ansible Playbook添加自定义连接插件及排查显示问题

我想要为Ansible编写一个自定义连接插件，仅用于某一个特定Playbook，并随该Playbook一同分发（同一Git仓库）。

根据Ansible官方文档说明：

若要仅在选定的一个或多个Playbook中使用独立插件，请将插件存储在包含Playbook的目录下对应plugin_type的子目录中（例如callback_plugins或inventory_plugins），这些目录必须以_plugins为后缀。插件类型完整列表请参见《Working with plugins》文档。

而《Working with plugins》页面提到：

你可以将自定义插件放入connection_plugins目录，以此扩展Ansible对其他传输方式（如SNMP或消息总线）的支持。

我按照文档操作，Playbook路径为./playbook.yaml，执行了以下命令创建插件文件：

mkdir connection_plugins
curl https://raw.githubusercontent.com/ansible-collections/community.aws/e80bf933412ea5c7ab2a94af945170cb2ebd900f/plugins/connection/aws_ssm.py | sed -e 's/aws_ssm/my_connector/g' > connection_plugins/my_connector.py

当前目录结构为：

• ./playbook.yaml
• ./connection_plugins/my_connector.py

我尝试用命令列出所有连接插件：

ansible-doc -t connection -l

但输出里没有my_connector插件。我怀疑插件放置位置不对，但完全是按文档操作的，所以有两个问题：

1. 仅用于邻近Playbook的自定义连接插件的正确放置位置是什么？
2. ansible-doc -t connection -l是否应该显示本地安装的插件？

问题解答 #

1. 自定义连接插件的正确放置位置 #

你当前的放置位置./connection_plugins/my_connector.py是完全正确的，符合Ansible官方文档要求。不过需要额外确认两个细节：

• 插件代码内的名称匹配：你用sed替换了aws_ssm为my_connector，要确保DOCUMENTATION块中的name字段已改为my_connector，同时插件类的命名（比如MyConnectorConnection）也和插件名称对应一致。
• 插件生效验证：无需依赖ansible-doc的输出，直接在Playbook中指定connection: my_connector执行，即可测试插件是否被正确加载。

2. ansible-doc是否显示本地插件？ #

默认情况下，ansible-doc -t connection -l只会显示系统级安装的插件（包括Ansible核心插件、通过包管理器/ansible-galaxy安装的集合插件），不会自动识别当前目录下的本地自定义插件。

如果要让ansible-doc识别本地插件，有两种方式：

• 通过环境变量临时加载：

  ANSIBLE_CONNECTION_PLUGINS=./connection_plugins ansible-doc -t connection -l
  

• 在当前目录创建ansible.cfg配置文件，添加如下内容：

  [defaults]
  connection_plugins = ./connection_plugins
  

  之后再执行ansible-doc -t connection -l，就能看到你的自定义插件了。

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