基础设施即代码 / 系统课时

排查模块失败与返回值

排查模块失败与返回值

模块失败时,终端上的一行 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 还能打印注册结果;生产逻辑不要用它掩盖真实失败。

yaml
- 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) }}"

运行:

bash
ansible-playbook -i localhost, -c local inspect-module.yml

预期输出中的关键部分为:

text
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 时,可以对最小复现增加详细度:

bash
ansible-playbook -i localhost, -c local inspect-module.yml -vvv

预期结果会比普通模式多出连接、模块执行与参数相关的调试信息,具体临时路径和环境值因主机而异,例如可能出现:

text
<localhost> EXEC /bin/sh -c '<PATH>'
fatal: [localhost]: FAILED! => ... "rc": 13, "stderr": "permission denied"

高详细度日志可能包含主机路径、模块参数甚至敏感变量,因此应只在受控环境中保存和分享。修复后再以普通详细度执行一次,确认任务不再失败,并验证真正的目标状态,而不是只确认 rc 变成零。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

排查模块失败与返回值

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通