Ansible 自定义模块如何处理错误直接 raise 异常与 fail_json 的正确用法【免费下载链接】ansibleAnsible is a radically simple IT automation platform that makes your applications and systems easier to deploy and maintain. Automate everything from code deployment to network configuration to cloud management, in a language that approaches plain English, using SSH, with no agents to install on remote systems. https://docs.ansible.com.项目地址: https://gitcode.com/GitHub_Trending/ans/ansible开发自定义 Python 模块时最常见的困惑是模块内部出错时到底该raise异常还是调用fail_json返回Ansible 当前的做法是——大多数情况下直接 raise 异常即可。AnsiballZ 包装器为 Python 模块提供了通用的异常处理器模块抛出的异常会被自动捕获并转换成标准的失败结果fail_json只在需要自定义模块返回结果时才必须使用。这篇文章基于仓库内的 context/error-handling.md 规范文档和 fail_json 实现给出两种写法的适用边界和验证方法。什么时候可以直接 raise 异常context/error-handling.md 中 In modules 一节给出的原则是In most cases, just raise an exception. The AnsiballZ wrapper now provides a general exception handler for Python modules, making use offail_jsonunnecessary, unless the module result needs to be customized.也就是说如果你只需要让任务失败、并把错误信息传回 controller直接抛异常就是正确写法if not os.path.exists(path): raise Exception(Configuration file not found: %s % path)配套的两条纪律同样来自该文档不要为了重新抛出而捕获异常Dont catch exceptions just to re-raise them除非新异常里能补充额外信息。对插件/模块失败而言上下文信息会自动附加细粒度的try/except/raise通常没有必要。不要在新异常中重复旧异常的 message。例如raise Exception(it broke: {ex}) from ex是文档明确列出的反模式因为 Ansible 内置的错误链机制会自动带上 cause/context 异常的消息。需要自定义失败结果时用 fail_jsonfail_json定义在 lib/ansible/module_utils/basic.py行为是在结果中写入failedTrue和msg清理临时文件后以退出码 1 结束成功返回对应的是exit_json退出码 0。当你需要往失败结果里塞额外的键值比如带上rc、cmd、stdout、details等字段才用fail_json这也是内置模块的典型写法例如basic.py中执行命令失败时self.fail_json(cmdself._clean_args(args), rcrc, stdoutstdout, stderrstderr, msgmsg)fail_json的exception参数有四种取值语义直接来自源码 docstring按需要选exception取值行为异常对象自动把异常的消息链含__cause__链上的消息与msg合并并用该异常的 traceback 生成格式化 traceback字符串直接作为格式化后的 traceback 写入结果None使用当前调用栈作为格式化 traceback不传默认从当前 pending 的异常获取格式化 traceback没有 pending 异常时退回当前调用栈注意两点限制traceback 只有在启用了错误 traceback 捕获时才会出现在结果里对应配置项是DISPLAY_TRACEBACK见 context/error-handling.md Tracebacks 一节。文档明确说明使用fail_json自定义失败结果时不需要再传exception参数来提供当前活跃的异常——不传时实现会自动处理见上表最后一行。延迟处理异常时try/except fail_json如果异常需要在try块里捕获、在别处再转换为模块失败deferred exception文档要求的写法是把捕获到的Exception实例通过exception参数传给fail_jsontry: result parse_config(path) except Exception as ex: module.fail_json(msgFailed to parse %s % path, exceptionex)错误细节收集和 traceback 格式化会由错误处理基础设施完成模块代码不用自己拼 traceback 文本。异常上下文优先用 raise from在另一个异常仍然活跃时再抛新异常原异常会成为新异常的__context__这通常不是想要的行为。文档要求大多数情况使用raise from并给出两个示例写法# 抑制原异常它没有帮助时 raise Exception(something) from None # 把捕获的异常设为新异常的 __cause__ raise Exception(something) from exraise from ex与上面fail_json(exceptionex)的消息链机制对应链路上的消息会被自动合并所以新异常的 message 只需简短描述发生了什么不要塞诊断信息或修复建议。需要用户可读的错误指引时用 AnsibleErrorAnsibleError支持message之外的两个参数来自 context/error-handling.md When and how to use AnsibleError 一节obj—— 通常是导致出错的变量本身不是Exception实例。如果该值带有Origin标记展示给用户的错误信息会带上触发错误的内容上下文。help_text—— 帮助用户理解如何解决错误的说明文字会显示在obj提供的上下文细节之后。这样message可以保持简短、只聚焦问题本身。文档同时提醒如果除了 message 之外不传其他参数用内置异常类型效果相同AnsibleError并没有额外收益。另外Display对象的warning和deprecated方法现在也接受help_text和obj参数新增的error_as_warning方法可以直接接收一个异常对象把捕获的异常转成 warning同时保留异常细节、traceback 和源对象上下文。如何本地验证模块的错误处理不需要跑完整 playbook 就能验证模块行为仓库自带 hacking/test-module.py 脚本脚本头部说明它是for testing modules without running through the entire guts of ansible。用法来自脚本头部注释模块路径替换为你要测试的模块文件路径-a后跟模块参数字符串./hacking/test-module.py -m lib/ansible/modules/command.py -a /bin/sleep 3常用选项脚本parse()中的定义-c/--check以 check mode 运行模块-n/--noexecute只生成不执行用于排查打包问题-o/--output把输出写入指定文件-D/--debugger指定 Python 调试器路径如/usr/bin/pdb。验证要点故意触发你写的失败分支观察脚本输出的 JSON——直接raise的异常应呈现为带消息的标准失败结果启用DISPLAY_TRACEBACK时能看到捕获的 tracebackfail_json的自定义键值应原样出现在结果中且没有重复拼接旧的异常消息。边界与例外Jinja 插件AnsibleFilterError和AnsibleLookupError这两个异常类型已不再需要按错误条件选择合适类型的普通异常即可。不要手工生成 tracebackcontroller 端和模块端Python的错误、警告、弃用警告都有标准化的 traceback 捕获是否展示由DISPLAY_TRACEBACK配置项控制。Jinja 之外的模块warn/deprecate方法调用同样会把 traceback 整理后传回 controller需启用捕获。参考文件规范见 context/error-handling.mdfail_json/exit_json实现见 lib/ansible/module_utils/basic.py本地验证工具见 hacking/test-module.py。【免费下载链接】ansibleAnsible is a radically simple IT automation platform that makes your applications and systems easier to deploy and maintain. Automate everything from code deployment to network configuration to cloud management, in a language that approaches plain English, using SSH, with no agents to install on remote systems. https://docs.ansible.com.项目地址: https://gitcode.com/GitHub_Trending/ans/ansible创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Ansible 自定义模块如何处理错误？直接 raise 异常与 fail_json 的正确用法
Ansible 自定义模块如何处理错误直接 raise 异常与 fail_json 的正确用法【免费下载链接】ansibleAnsible is a radically simple IT automation platform that makes your applications and systems easier to deploy and maintain. Automate everything from code deployment to network configuration to cloud management, in a language that approaches plain English, using SSH, with no agents to install on remote systems. https://docs.ansible.com.项目地址: https://gitcode.com/GitHub_Trending/ans/ansible开发自定义 Python 模块时最常见的困惑是模块内部出错时到底该raise异常还是调用fail_json返回Ansible 当前的做法是——大多数情况下直接 raise 异常即可。AnsiballZ 包装器为 Python 模块提供了通用的异常处理器模块抛出的异常会被自动捕获并转换成标准的失败结果fail_json只在需要自定义模块返回结果时才必须使用。这篇文章基于仓库内的 context/error-handling.md 规范文档和 fail_json 实现给出两种写法的适用边界和验证方法。什么时候可以直接 raise 异常context/error-handling.md 中 In modules 一节给出的原则是In most cases, just raise an exception. The AnsiballZ wrapper now provides a general exception handler for Python modules, making use offail_jsonunnecessary, unless the module result needs to be customized.也就是说如果你只需要让任务失败、并把错误信息传回 controller直接抛异常就是正确写法if not os.path.exists(path): raise Exception(Configuration file not found: %s % path)配套的两条纪律同样来自该文档不要为了重新抛出而捕获异常Dont catch exceptions just to re-raise them除非新异常里能补充额外信息。对插件/模块失败而言上下文信息会自动附加细粒度的try/except/raise通常没有必要。不要在新异常中重复旧异常的 message。例如raise Exception(it broke: {ex}) from ex是文档明确列出的反模式因为 Ansible 内置的错误链机制会自动带上 cause/context 异常的消息。需要自定义失败结果时用 fail_jsonfail_json定义在 lib/ansible/module_utils/basic.py行为是在结果中写入failedTrue和msg清理临时文件后以退出码 1 结束成功返回对应的是exit_json退出码 0。当你需要往失败结果里塞额外的键值比如带上rc、cmd、stdout、details等字段才用fail_json这也是内置模块的典型写法例如basic.py中执行命令失败时self.fail_json(cmdself._clean_args(args), rcrc, stdoutstdout, stderrstderr, msgmsg)fail_json的exception参数有四种取值语义直接来自源码 docstring按需要选exception取值行为异常对象自动把异常的消息链含__cause__链上的消息与msg合并并用该异常的 traceback 生成格式化 traceback字符串直接作为格式化后的 traceback 写入结果None使用当前调用栈作为格式化 traceback不传默认从当前 pending 的异常获取格式化 traceback没有 pending 异常时退回当前调用栈注意两点限制traceback 只有在启用了错误 traceback 捕获时才会出现在结果里对应配置项是DISPLAY_TRACEBACK见 context/error-handling.md Tracebacks 一节。文档明确说明使用fail_json自定义失败结果时不需要再传exception参数来提供当前活跃的异常——不传时实现会自动处理见上表最后一行。延迟处理异常时try/except fail_json如果异常需要在try块里捕获、在别处再转换为模块失败deferred exception文档要求的写法是把捕获到的Exception实例通过exception参数传给fail_jsontry: result parse_config(path) except Exception as ex: module.fail_json(msgFailed to parse %s % path, exceptionex)错误细节收集和 traceback 格式化会由错误处理基础设施完成模块代码不用自己拼 traceback 文本。异常上下文优先用 raise from在另一个异常仍然活跃时再抛新异常原异常会成为新异常的__context__这通常不是想要的行为。文档要求大多数情况使用raise from并给出两个示例写法# 抑制原异常它没有帮助时 raise Exception(something) from None # 把捕获的异常设为新异常的 __cause__ raise Exception(something) from exraise from ex与上面fail_json(exceptionex)的消息链机制对应链路上的消息会被自动合并所以新异常的 message 只需简短描述发生了什么不要塞诊断信息或修复建议。需要用户可读的错误指引时用 AnsibleErrorAnsibleError支持message之外的两个参数来自 context/error-handling.md When and how to use AnsibleError 一节obj—— 通常是导致出错的变量本身不是Exception实例。如果该值带有Origin标记展示给用户的错误信息会带上触发错误的内容上下文。help_text—— 帮助用户理解如何解决错误的说明文字会显示在obj提供的上下文细节之后。这样message可以保持简短、只聚焦问题本身。文档同时提醒如果除了 message 之外不传其他参数用内置异常类型效果相同AnsibleError并没有额外收益。另外Display对象的warning和deprecated方法现在也接受help_text和obj参数新增的error_as_warning方法可以直接接收一个异常对象把捕获的异常转成 warning同时保留异常细节、traceback 和源对象上下文。如何本地验证模块的错误处理不需要跑完整 playbook 就能验证模块行为仓库自带 hacking/test-module.py 脚本脚本头部说明它是for testing modules without running through the entire guts of ansible。用法来自脚本头部注释模块路径替换为你要测试的模块文件路径-a后跟模块参数字符串./hacking/test-module.py -m lib/ansible/modules/command.py -a /bin/sleep 3常用选项脚本parse()中的定义-c/--check以 check mode 运行模块-n/--noexecute只生成不执行用于排查打包问题-o/--output把输出写入指定文件-D/--debugger指定 Python 调试器路径如/usr/bin/pdb。验证要点故意触发你写的失败分支观察脚本输出的 JSON——直接raise的异常应呈现为带消息的标准失败结果启用DISPLAY_TRACEBACK时能看到捕获的 tracebackfail_json的自定义键值应原样出现在结果中且没有重复拼接旧的异常消息。边界与例外Jinja 插件AnsibleFilterError和AnsibleLookupError这两个异常类型已不再需要按错误条件选择合适类型的普通异常即可。不要手工生成 tracebackcontroller 端和模块端Python的错误、警告、弃用警告都有标准化的 traceback 捕获是否展示由DISPLAY_TRACEBACK配置项控制。Jinja 之外的模块warn/deprecate方法调用同样会把 traceback 整理后传回 controller需启用捕获。参考文件规范见 context/error-handling.mdfail_json/exit_json实现见 lib/ansible/module_utils/basic.py本地验证工具见 hacking/test-module.py。【免费下载链接】ansibleAnsible is a radically simple IT automation platform that makes your applications and systems easier to deploy and maintain. Automate everything from code deployment to network configuration to cloud management, in a language that approaches plain English, using SSH, with no agents to install on remote systems. https://docs.ansible.com.项目地址: https://gitcode.com/GitHub_Trending/ans/ansible创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考