插件系统

相关源文件

• changelogs/fragments/async_really_true.yml
• lib/ansible/config/ansible_builtin_runtime.yml
• lib/ansible/executor/module_common.py
• lib/ansible/executor/powershell/async_watchdog.ps1
• lib/ansible/executor/powershell/async_wrapper.ps1
• lib/ansible/executor/powershell/module_manifest.py
• lib/ansible/modules/async_status.py
• lib/ansible/modules/async_wrapper.py
• lib/ansible/plugins/action/__init__.py
• lib/ansible/plugins/action/async_status.py
• lib/ansible/plugins/cache/jsonfile.py
• lib/ansible/plugins/loader.py
• lib/ansible/plugins/test/finished.yml
• test/integration/targets/async/tasks/main.yml
• test/units/plugins/action/test_action.py

Ansible 的插件系统是一个核心组件，通过模块化、可插拔的代码提供扩展性。本页面解释了 Ansible 的插件架构如何工作，包括发现机制、加载过程和路由系统，这些系统允许插件被找到和执行。

有关模块等特定插件实现的信息，请参阅 模块系统。

插件系统概述

Ansible 的插件系统通过为各种功能类型提供接口来实现可扩展性。插件是集成了 Ansible 核心的专用 Python 类，以定义明确的方式扩展其功能。

来源： lib/ansible/config/ansible_builtin_runtime.yml lib/ansible/plugins/lookup/template.py

插件发现与加载

Ansible 通过按特定顺序搜索预定义的一组目录来发现插件。这包括内置插件目录和用户定义的插件路径。

来源： lib/ansible/config/ansible_builtin_runtime.yml3-7 lib/ansible/plugins/lookup/template.py115-117

插件路由系统

插件路由系统定义在 ansible_builtin_runtime.yml 中，它允许插件从一个位置重定向到另一个位置。这对于以下情况尤其重要：

1. 在不破坏向后兼容性的情况下将插件迁移到集合
2. 维护与旧插件名称的兼容性
3. 允许覆盖内置插件

路由配置将插件名称映射到其实际实现

plugin_routing:
  connection:
    redirected_local:
      redirect: ansible.builtin.local
    podman:
      redirect: containers.podman.podman
  modules:
    formerly_core_ping:
      redirect: testns.testcoll.ping

来源： lib/ansible/config/ansible_builtin_runtime.yml3-93

插件类型

Ansible 包含多种插件类型，每种插件在架构中都有特定的用途

插件类型	目的	示例
操作	控制模块的执行流程	template, copy, file
连接	管理到目标主机的连接	ssh, winrm, local
过滤器	在模板中转换数据	to_yaml, to_json, ipaddr
Lookup（查找）	从外部源检索数据	file, env, pipe, template
模块	实现任务功能	command, apt, yum, service
策略	控制跨主机的任务执行	linear, free, debug
缓存	存储和检索缓存数据	jsonfile, memory, redis
模板	处理模板操作	Jinja2 模板

来源： lib/ansible/plugins/lookup/template.py7-101 lib/ansible/plugins/cache/jsonfile.py7-41 lib/ansible/plugins/doc_fragments/template_common.py12-120

模板插件集成

模板系统是插件的关键集成点，因为许多插件需要处理模板或使用模板化数据。 Templar 类提供了模板操作的接口

插件可以通过以下关键方法访问模板功能

• template()：递归处理模板
• evaluate_expression()：评估可信表达式
• resolve_variable_expression()：安全地解析变量引用

来源： lib/ansible/template/__init__.py39-326 lib/ansible/plugins/lookup/template.py116-174

Lookup 插件示例

模板查找插件展示了插件如何与 Ansible 的核心系统集成

模板查找插件的关键点

1. 它使用搜索路径定位模板文件
2. 它创建一个具有适当变量和上下文的 Templar
3. 它使用 Templar 渲染模板
4. 它将渲染的内容返回给调用者

来源： lib/ansible/plugins/lookup/template.py114-178

Action 插件与模板

模板 Action 插件之类的 Action 插件展示了模板如何与任务执行集成

1. Action 插件接收任务参数
2. 它定位并加载模板源
3. 它使用任务变量创建一个 Templar
4. 它使用适当的选项渲染模板
5. 它使用 copy 动作传输渲染的内容

这种架构确保了模板渲染和文件操作之间的清晰分离。

来源： lib/ansible/plugins/action/template.py31-177

Cache 插件示例

Cache 插件展示了更简单的插件结构

这个 JSON 文件缓存插件展示了缓存插件所需的最小接口：加载和存储数据的方法。

来源： lib/ansible/plugins/cache/jsonfile.py49-56

条件评估

插件经常与 Ansible 的条件评估系统进行交互。 Conditional 类提供了条件执行的基础功能

插件可以使用条件根据变量值或表达式评估来控制其执行。

来源： lib/ansible/playbook/conditional.py26-39

插件开发指南

开发自定义 Ansible 插件时，请遵循以下指南

1. 继承自适当的基类以匹配您的插件类型
2. 实现必需的方法，这些方法由基类定义
3. 记录您的插件，使用 Ansible 的 DOCUMENTATION、EXAMPLES 和 RETURN 字符串
4. 优雅地处理错误并提供适当的错误消息
5. 测试您的插件，使用 Ansible 的测试框架

所有插件都应遵循 Ansible 的编码标准，并设计为与未来 Ansible 版本兼容。

总结

Ansible 的插件系统提供了一个灵活、可扩展的架构来添加功能。插件加载、路由和发现机制协同工作，支持丰富的内置和社区开发的插件生态系统。模板是许多插件的关键集成点，而模块化设计允许 Ansible 的功能不断演进。