基础设施即代码 / 系统课时
排查模块失败与返回值
排查模块失败与返回值
模块失败时,终端上的一行 FAILED! 只是结果摘要。真正有用的线索通常在注册结果里的 rc、stdout、stderr、msg、failed,必要时还有 exception。本篇用一个可控失败示例建立字段到根因的定位顺序。
学习目标
- 读取常见模块返回字段并判断每个字段能说明什么
- 用
register保留失败结果,在 Playbook 中继续输出诊断信息 - 区分命令退出码、模块参数错误、远端环境错误和模块内部异常
先判断失败发生在哪一层
排障时先看 msg,再看模块类型决定是否检查 rc、stdout 和 stderr。命令类模块通常能提供进程退出码;文件、包管理、云资源等模块未必存在 rc,此时强行围绕退出码排查反而会偏离根因。
| 字段 | 主要含义 | 常见用途 |
|---|---|---|
rc |
远端命令退出码 | 判断外部程序是否以非零状态结束 |
stdout |
标准输出 | 查看命令正常返回的数据 |
stderr |
标准错误 | 查看权限、路径、参数或外部程序报错 |
msg |
模块给出的失败摘要 | 快速识别参数、状态或执行阶段 |
exception |
模块或 Python 异常信息,未必总存在 | 处理模块内部异常或 traceback |
failed |
Ansible 对本次结果的失败判定 | 判断任务状态,而不是替代根因分析 |
rc != 0 很重要,但它只适用于确实执行了外部进程且返回了退出码的场景。对于没有 rc 的模块,应优先相信模块自己的 msg 和结构化返回字段。
用 register 保留一个可控失败
下面的 Playbook 故意让 /bin/sh 以退出码 13 结束,同时分别产生标准输出和标准错误。ignore_errors: true 只用于教学排障,让后续 debug 还能打印注册结果;生产逻辑不要用它掩盖真实失败。
- name: Inspect module failure
hosts: localhost
gather_facts: false
tasks:
- name: Run a command that fails deliberately
ansible.builtin.command:
argv:
- /bin/sh
- -c
- "printf 'ok-output\n'; printf 'permission denied\n' >&2; exit 13"
register: command_result
changed_when: false
ignore_errors: true
- name: Print diagnostic fields
ansible.builtin.debug:
msg:
- "rc={{ command_result.rc }}"
- "stdout={{ command_result.stdout }}"
- "stderr={{ command_result.stderr }}"
- "msg={{ command_result.msg | default('<none>') }}"
- "failed={{ command_result.failed | default(false) }}"运行:
ansible-playbook -i localhost, -c local inspect-module.yml预期输出中的关键部分为:
TASK [Run a command that fails deliberately] ***
fatal: [localhost]: FAILED! => ...ignoring
TASK [Print diagnostic fields] ***
ok: [localhost] => {
"msg": [
"rc=13",
"stdout=ok-output",
"stderr=permission denied",
"msg=non-zero return code",
"failed=True"
]
}此时可以直接得出:模块成功启动了外部命令,但外部进程主动以非零状态结束;stderr 又给出了权限类线索。相比只看 FAILED!,这组字段已经把问题范围缩小到命令自身或其运行环境。
按字段组合推断根因
如果 rc 非零且 stderr 有明确错误,优先处理外部命令问题,例如权限、文件不存在、参数错误或依赖缺失。若 rc 为零但任务仍失败,应检查模块是否根据返回内容、状态检查或自定义 failed_when 判定失败。
如果没有 rc,但 msg 指向 unsupported parameters、缺少必填参数或类型不匹配,问题通常发生在模块参数校验阶段;这时远端命令甚至可能还没有执行。若 msg 很泛化,而高详细度输出出现 Python traceback 或 exception,再考虑模块版本、远端 Python 环境、第三方 collection 或模块自身缺陷。
在需要时提高详细度
当普通输出不足以确认模块参数、连接过程或 traceback 时,可以对最小复现增加详细度:
ansible-playbook -i localhost, -c local inspect-module.yml -vvv预期结果会比普通模式多出连接、模块执行与参数相关的调试信息,具体临时路径和环境值因主机而异,例如可能出现:
<localhost> EXEC /bin/sh -c '<PATH>'
fatal: [localhost]: FAILED! => ... "rc": 13, "stderr": "permission denied"高详细度日志可能包含主机路径、模块参数甚至敏感变量,因此应只在受控环境中保存和分享。修复后再以普通详细度执行一次,确认任务不再失败,并验证真正的目标状态,而不是只确认 rc 变成零。