如何在Ansible连接插件中访问指定主机的清单变量？

核心问题原因 #

连接插件无法读取清单变量，通常是变量命名不符合Ansible插件规则、DOCUMENTATION选项定义错误，或者插件初始化流程不正确导致的。

分步解决方法 #

1. 遵循清单变量命名规则 #

Ansible连接插件的配置变量必须以ansible_{你的连接插件名}_为前缀。比如你的插件名为myapi，清单中定义设备API地址时，变量名应为ansible_myapi_address，而非直接用address。

示例清单（INI格式）：

[api_devices]
device_1 ansible_connection=myapi ansible_myapi_address=https://192.168.1.100/api

示例清单（YAML格式）：

api_devices:
  hosts:
    device_1:
      ansible_connection: myapi
      ansible_myapi_address: https://192.168.1.100/api

2. 修正插件DOCUMENTATION块的选项定义 #

在插件的DOCUMENTATION中，需要明确每个选项对应的清单变量名（通过vars字段），确保Ansible能正确映射变量：

DOCUMENTATION = '''
---
connection: myapi
short_description: Connect to network devices via custom API
description:
  - This connection plugin provides access to devices managed only via API.
options:
  address:
    description: Full URL/IP address of the device's API endpoint
    required: true
    vars:
      - name: ansible_myapi_address
  # 其他选项同理
'''

如果未定义vars字段，Ansible会默认使用ansible_{插件名}_{选项名}的格式查找变量，但手动指定vars能避免歧义。

3. 规范插件初始化流程 #

• 确保插件类继承自ansible.plugins.connection.ConnectionBase
• 不要手动调用self.set_options()，Ansible的插件框架会自动完成选项加载。手动调用会覆盖框架加载的清单变量，导致读取失败。
• 应在connect方法中调用self.get_option('address')，此时框架已经完成所有变量的加载：

from ansible.plugins.connection import ConnectionBase

class Connection(ConnectionBase):
    transport = 'myapi'
    has_pipelining = False

    def __init__(self, play_context, new_stdin, *args, **kwargs):
        super().__init__(play_context, new_stdin, *args, **kwargs)
        # 不要在这里调用get_option，变量还未加载完成

    def connect(self):
        if not self._connected:
            # 在这里获取选项值
            self.address = self.get_option('address')
            # 后续API连接逻辑
            self._connected = True

    def close(self):
        self._connected = False

4. 调试与验证 #

• 用以下命令确认设备变量是否正确加载：

  ansible-inventory --host device_1 --vars
  

  输出中应包含ansible_myapi_address字段。
• 运行剧本时添加-vvv参数，查看详细日志，确认Ansible是否在查找正确的变量名。
• 在插件的connect方法中临时添加打印语句，排查变量是否被传入：

  def connect(self):
      print("Task vars:", self._task_vars)
      print("Loaded options:", self._options)
      # 后续逻辑
  

避免使用ansible_connection: local的替代方案 #

使用local连接会混淆连接逻辑与任务逻辑，不符合职责分离原则。按照上述步骤修正后，连接插件可以独立完成API连接的配置与初始化，无需在任务中额外传参。

内容的提问来源于stack exchange，提问作者Piotr Gabryś