调试任务

Ansible 提供了一个任务调试器，以便您可以在执行过程中修复错误，而无需编辑剧本并再次运行它来查看您的更改是否有效。您可以在任务上下文中访问调试器的所有功能。您可以检查或设置变量的值，更新模块参数，并使用新的变量和参数重新运行任务。调试器使您可以解决故障的原因并继续执行剧本。

启用调试器

默认情况下，调试器未启用。如果您想在执行剧本期间调用调试器，您必须先启用它。

使用以下三种方法之一来启用调试器

  • 使用 debugger 关键字

  • 在配置或环境变量中，或

  • 作为策略

使用 debugger 关键字启用调试器

版本 2.5 中的新增功能。

您可以使用 debugger 关键字为特定剧本、角色、块或任务启用（或禁用）调试器。此选项在开发或扩展剧本、剧本和角色时特别有用。您可以在新的或更新的任务上启用调试器。如果它们失败，您可以有效地修复错误。debugger 关键字接受五个值

值

结果

始终

始终调用调试器，无论结果如何

从不

从不调用调试器，无论结果如何

失败时

仅在任务失败时调用调试器

不可达时

仅在主机不可达时调用调试器

跳过时

仅在任务被跳过时调用调试器

当您使用 debugger 关键字时，您指定的 value 会覆盖任何全局配置以启用或禁用调试器。如果您在多个级别定义 debugger，例如在角色和任务中，Ansible 会尊重最细粒度的定义。剧本或角色级别上的定义适用于该剧本或角色中的所有块和任务，除非它们指定了不同的值。块级别上的定义会覆盖剧本或角色级别上的定义，并适用于该块中的所有任务，除非它们指定了不同的值。任务级别上的定义始终适用于该任务；它会覆盖块、剧本或角色级别上的定义。

使用 debugger 关键字的示例

在任务上设置 debugger 关键字的示例

- name: Execute a command
  ansible.builtin.command: "false"
  debugger: on_failed

在剧本上设置 debugger 关键字的示例

- name: My play
  hosts: all
  debugger: on_skipped
  tasks:
    - name: Execute a command
      ansible.builtin.command: "true"
      when: False

在多个级别设置 debugger 关键字的示例

- name: Play
  hosts: all
  debugger: never
  tasks:
    - name: Execute a command
      ansible.builtin.command: "false"
      debugger: on_failed

在此示例中，调试器在剧本级别设置为 never，在任务级别设置为 on_failed。如果任务失败，Ansible 会调用调试器，因为任务的定义会覆盖其父剧本的定义。

在配置或环境变量中启用调试器

版本 2.5 中的新增功能。

您可以使用 ansible.cfg 中的设置或使用环境变量在全局范围内启用任务调试器。唯一的选择是 True 或 False。如果您将配置选项或环境变量设置为 True，Ansible 默认情况下会在失败的任务上运行调试器。

要从 ansible.cfg 启用任务调试器，请将此设置添加到 [defaults] 部分

[defaults]
enable_task_debugger = True

要使用环境变量启用任务调试器，请在运行剧本时传递变量

ANSIBLE_ENABLE_TASK_DEBUGGER=True ansible-playbook -i hosts site.yml

当您在全局范围内启用调试器时，每个失败的任务都会调用调试器，除非角色、剧本、块或任务明确地禁用了调试器。如果您需要更细粒度地控制触发调试器的条件，请使用 debugger 关键字。

将调试器作为策略启用

如果您正在运行旧的剧本或角色，您可能会看到调试器作为 策略 启用。您可以在剧本级别、ansible.cfg 中或使用环境变量 ANSIBLE_STRATEGY=debug 来执行此操作。例如

- hosts: test
  strategy: debug
  tasks:
  ...

或在 ansible.cfg 中

[defaults]
strategy = debug

注意

这种向后兼容的方法（与 2.5 之前的 Ansible 版本匹配）可能会在将来的版本中被删除。

解决调试器中的错误

Ansible 调用调试器后，您可以使用七个 调试器命令 来解决 Ansible 遇到的错误。请考虑此示例剧本，它定义了 var1 变量，但在任务中错误地使用了未定义的 wrong_var 变量。

- hosts: test
  debugger: on_failed
  gather_facts: false
  vars:
    var1: value1
  tasks:
    - name: Use a wrong variable
      ansible.builtin.ping: data={{ wrong_var }}

如果运行此剧本，Ansible 会在任务失败时调用调试器。从调试提示符，您可以更改模块参数或变量并再次运行任务。

PLAY ***************************************************************************

TASK [wrong variable] **********************************************************
fatal: [192.0.2.10]: FAILED! => {"failed": true, "msg": "ERROR! 'wrong_var' is undefined"}
Debugger invoked
[192.0.2.10] TASK: wrong variable (debug)> p result._result
{'failed': True,
 'msg': 'The task includes an option with an undefined variable. The error '
        "was: 'wrong_var' is undefined\n"
        '\n'
        'The error appears to have been in '
        "'playbooks/debugger.yml': line 7, "
        'column 7, but may\n'
        'be elsewhere in the file depending on the exact syntax problem.\n'
        '\n'
        'The offending line appears to be:\n'
        '\n'
        '  tasks:\n'
        '    - name: wrong variable\n'
        '      ^ here\n'}
[192.0.2.10] TASK: wrong variable (debug)> p task.args
{u'data': u'{{ wrong_var }}'}
[192.0.2.10] TASK: wrong variable (debug)> task.args['data'] = '{{ var1 }}'
[192.0.2.10] TASK: wrong variable (debug)> p task.args
{u'data': '{{ var1 }}'}
[192.0.2.10] TASK: wrong variable (debug)> redo
ok: [192.0.2.10]

PLAY RECAP *********************************************************************
192.0.2.10               : ok=1    changed=0    unreachable=0    failed=0

在调试器中将任务参数更改为使用 var1 而不是 wrong_var 使任务成功运行。

可用调试命令

您可以在调试提示符处使用以下七个命令

命令

快捷键

操作

打印

p

打印有关任务的信息

task.args[key] = value

无快捷键

更新模块参数

task_vars[key] = value

无快捷键

更新任务变量（您必须update_task 接下来）

update_task

u

使用更新的任务变量重新创建任务

重做

r

再次运行任务

继续

c

继续执行，从下一个任务开始

退出

q

退出调试器

有关更多详细信息，请参阅下面的各个描述和示例。

更新参数命令

task.args[*key*] = *value* 更新模块参数。此示例剧本包含一个无效的包名称。

- hosts: test
  strategy: debug
  gather_facts: true
  vars:
    pkg_name: not_exist
  tasks:
    - name: Install a package
      ansible.builtin.apt: name={{ pkg_name }}

运行剧本时，无效的包名称会触发错误，Ansible 会调用调试器。可以通过查看并更新模块参数来修复包名称。

[192.0.2.10] TASK: install package (debug)> p task.args
{u'name': u'{{ pkg_name }}'}
[192.0.2.10] TASK: install package (debug)> task.args['name'] = 'bash'
[192.0.2.10] TASK: install package (debug)> p task.args
{u'name': 'bash'}
[192.0.2.10] TASK: install package (debug)> redo

更新模块参数后，使用 redo 命令重新运行任务，使用新的参数。

更新变量命令

task_vars[*key*] = *value* 更新 task_vars。您可以通过查看并更新任务变量来修复上述剧本，而不是模块参数。

[192.0.2.10] TASK: install package (debug)> p task_vars['pkg_name']
u'not_exist'
[192.0.2.10] TASK: install package (debug)> task_vars['pkg_name'] = 'bash'
[192.0.2.10] TASK: install package (debug)> p task_vars['pkg_name']
'bash'
[192.0.2.10] TASK: install package (debug)> update_task
[192.0.2.10] TASK: install package (debug)> redo

更新任务变量后，必须使用 update_task 加载新变量，然后再使用 redo 重新运行任务。

注意

在 2.5 版本中，将 vars 更新为 task_vars，以避免与 vars() Python 函数冲突。

更新任务命令

版本 2.8 中的新功能。

u 或 update_task 使用更新后的任务变量从原始任务数据结构和模板重新创建任务。有关使用示例，请参阅 更新变量命令 条目。

Redo 命令

r 或 redo 重新运行任务。

Continue 命令

c 或 continue 继续执行，从下一个任务开始。

Quit 命令

q 或 quit 退出调试器。剧本执行将被中止。

调试器如何与 free 策略交互

启用默认的 linear 策略时，Ansible 会在调试器处于活动状态时暂停执行，并在您输入 redo 命令后立即运行被调试的任务。但是，启用 free 策略时，Ansible 不会等待所有主机，并且可能会在某个主机上的任务失败之前在另一个主机上排队后续任务。使用 free 策略时，Ansible 不会在调试器处于活动状态时排队或执行任何任务。但是，所有排队的任务都将保留在队列中，并在您退出调试器后立即运行。如果使用 redo 从调试器重新安排任务，其他排队的任务可能会在您重新安排的任务之前执行。有关策略的更多信息，请参阅 控制剧本执行：策略和其他。

另请参阅

执行剧本进行故障排除

调试或测试时运行剧本

Ansible 剧本

剧本简介

通信

有问题？需要帮助？想分享你的想法？请访问 Ansible 通信指南