Ansible通过自定义模块扩展能力，需用Python编写可执行脚本，接收JSON参数并返回含changed、msg等字段的JSON结果，存放于library/目录，支持幂等性且可直接在Playbook中调用。

Ansible 本身不直接执行任务，而是通过模块来完成具体操作。它的扩展性核心就体现在——你可以用任意语言（Python 为主）编写自定义模块，无缝集成进 Ansible 工作流，补足内置模块覆盖不到的场景。

为什么需要自定义模块

内置模块虽多（如 copy、apt、service），但面对以下情况时往往力不从心：

• 调用企业内部 API（如 CMDB 查询、工单系统触发）
• 操作私有硬件或专用设备（如网络设备 CLI、IoT 设备固件升级）
• 执行复杂逻辑判断（比如多条件组合校验后再决定是否重启服务）
• 复用已有脚本或二进制工具（如 Python 封装的部署包校验器、Go 写的配置生成器）

自定义模块的基本要求

一个可用的 Ansible 模块本质就是一个可执行脚本，需满足三点：

• 入口清晰：接收 JSON 格式的参数输入（通常由 Ansible 自动传入），输出也是标准 JSON（含 changed、msg、failed 等字段）
• 位置明确：放在 library/ 目录下（项目级）或 /usr/share/ansible/modules/（全局级），Ansible 会自动发现
• 无依赖污染：避免硬编码路径或依赖未预装的 Python 包；若必须依赖，应在文档中说明并建议用 pip 安装

一个最小可行的 Python 模块示例

比如写一个检查磁盘剩余空间是否低于阈值的模块 disk_check.py：

它接收 min_free_gb 参数，返回 failed: true 如果不足，并附带当前可用空间信息。Ansible 调用时写法为：- disk_check: min_free_gb=10。模块无需安装额外包，纯标准库即可运行，也天然支持幂等性判断。

如何在 Playbook 中使用

只要模块文件放到正确位置，用法和内置模块完全一致：

• 在 task 中直接引用模块名：- name: Check disk space disk_check: min_free_gb=5
• 支持 args、loop、when 等所有标准语法
• 可通过 ansible-doc -s disk_check 查看参数说明（需模块内含文档字符串）
• 错误信息、变更状态、返回数据都会被 Ansible 统一捕获和展示