Ansible 模块开发指南（基于 Ansible 2.8 及以上版本）

Ansible 是一个强大的自动化运维工具，使用 Python 开发自定义模块可以扩展其功能。模块是 Ansible 的核心组件，用于在目标主机上执行特定任务（如文件管理、服务部署）。本指南将逐步指导您如何开发一个简单的 Ansible 模块，确保结构清晰、可靠。开发前，您需具备：

• 基础 Python 知识。
• Ansible 基础（了解 Playbook 和 Inventory）。
• YAML 语法熟悉。

步骤 1: 理解模块结构

Ansible 模块是用 Python 编写的脚本，必须遵循以下规则：

• 模块文件以 .py 结尾。
• 使用 AnsibleModule 类处理输入参数和输出。
• 输出必须是 JSON 格式，包含 changed（布尔值，表示状态是否改变）、msg（消息）等字段。
• 模块应幂等（多次执行结果相同）。

步骤 2: 创建模块文件

在您的 Ansible 项目目录中，创建一个 library/ 文件夹（如果不存在），用于存放自定义模块。例如：

• 项目路径：/path/to/your_ansible_project/
• 模块文件：/path/to/your_ansible_project/library/my_custom_module.py

步骤 3: 编写 Python 代码

以下是一个简单示例模块：创建一个文件并写入内容。模块名为 my_custom_module，支持参数 path（文件路径）和 content（文件内容）。

#!/usr/bin/python
# -*- coding: utf-8 -*-

from ansible.module_utils.basic import AnsibleModule
import os

def main():
    # 定义模块参数
    module_args = dict(
        path=dict(type='str', required=True),
        content=dict(type='str', required=True)
    )

    # 初始化 AnsibleModule
    module = AnsibleModule(
        argument_spec=module_args,
        supports_check_mode=True
    )

    # 获取参数
    path = module.params['path']
    content = module.params['content']

    # 检查模式（dry run）：不实际执行
    if module.check_mode:
        module.exit_json(changed=False, msg="Check mode: no changes made")

    # 主逻辑：创建或更新文件
    changed = False
    msg = ""

    try:
        # 如果文件不存在或内容不同，则写入
        if not os.path.exists(path) or open(path, 'r').read() != content:
            with open(path, 'w') as f:
                f.write(content)
            changed = True
            msg = f"File {path} created or updated"
        else:
            msg = f"File {path} already exists with same content"
    except Exception as e:
        module.fail_json(msg=f"Error: {str(e)}")

    # 输出结果
    module.exit_json(changed=changed, msg=msg)

if __name__ == '__main__':
    main()

代码解释

• 参数处理：module_args 定义输入参数，required=True 表示必填。
• 幂等性：通过检查文件是否存在和内容是否相同，确保多次执行不会重复改变状态。
• 错误处理：module.fail_json() 用于返回错误；module.exit_json() 用于成功输出。
• 支持 check mode：supports_check_mode=True 允许在 Ansible Playbook 中使用 --check 参数测试而不实际执行。

步骤 4: 测试模块

在 Playbook 中调用您的模块。创建一个测试 Playbook 文件，例如 test_playbook.yml：

---
- name: Test custom module
  hosts: localhost  # 或您的目标主机组
  tasks:
    - name: Create a file
      my_custom_module:  # 模块名对应文件名（不含.py）
        path: "/tmp/test_file.txt"
        content: "Hello, Ansible!"
      register: result

    - name: Debug output
      debug:
        var: result

运行测试：

ansible-playbook test_playbook.yml --check  # 测试模式
ansible-playbook test_playbook.yml  # 实际执行

• 检查输出：确保 changed 和 msg 符合预期。

步骤 5: 最佳实践

• 模块优化：
  • 添加文档字符串（docstring）说明模块用途和参数，便于 ansible-doc 查看。
  • 支持更多参数类型（如 choices 限制选项）。
  • 使用 os.path 等标准库确保跨平台兼容。
• 错误处理：捕获所有异常，避免模块崩溃。
• 性能：避免长时间运行操作；复杂任务可拆分为多个模块。
• 版本兼容：Ansible 2.8+ 兼容此方法，但测试时确认您的 Ansible 版本（运行 ansible --version）。

总结

开发 Ansible 模块是提升自动化效率的关键。通过本指南，您可以创建自定义模块来处理运维任务。实践中，从简单模块开始，逐步扩展功能。参考 Ansible 官方文档（如 Module Development Guide）深入学习。遇到问题时，使用 ansible-doc 查看现有模块源码作为参考。