Отладка задач

Ansible предлагает отладчик задач, позволяющий исправлять ошибки во время выполнения, вместо того, чтобы редактировать плейбук и повторно запускать его, чтобы убедиться, что изменение сработало. У вас есть доступ ко всем функциям отладчика в контексте задачи. Вы можете проверять или устанавливать значения переменных, обновлять аргументы модуля и повторно запускать задачу с новыми переменными и аргументами. Отладчик позволяет определить причину сбоя и продолжить выполнение плейбука.

• Включение отладчика

  • Включение отладчика с ключевым словом debugger

    • Примеры использования ключевого слова debugger
  • Включение отладчика в конфигурации или переменной окружения
  • Включение отладчика как стратегии
• Устранение ошибок в отладчике

• Доступные команды отладки

  • Команда print
  • Команда обновления аргументов
  • Команда обновления переменных
  • Команда обновления задачи
  • Команда повторного выполнения
  • Команда продолжения
  • Команда выхода
• Как отладчик взаимодействует со стратегией свободного выполнения

Включение отладчика

Отладчик по умолчанию не включен. Если вы хотите вызвать отладчик во время выполнения плейбука, вы должны его сначала включить.

Используйте один из следующих трех способов для включения отладчика:

• с использованием ключевого слова debugger
• в конфигурации или переменной окружения, или
• как стратегию

Включение отладчика с ключевым словом debugger

Вы можете использовать ключевое слово debugger для включения (или отключения) отладчика для конкретного плейя, роли, блока или задачи. Этот вариант особенно полезен при разработке или расширении плейбуков, плей и ролей. Вы можете включить отладчик в новых или обновленных задачах. Если они завершатся ошибкой, вы сможете эффективно исправить ошибки. Ключевое слово debugger принимает пять значений:

Когда вы используете ключевое слово debugger, указанное вами значение переопределяет любую глобальную конфигурацию для включения или отключения отладчика. Если вы определяете 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 вызывает отладчик, поскольку определение на уровне задачи переопределяет определение в родительском плейе.

Включение отладчика в конфигурации или переменной окружения

Вы можете включить отладчик задач глобально, используя настройку в 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

Устранение ошибок в отладчике

После того, как Ansible вызовет отладчик, вы можете использовать семь команд отладчика, чтобы устранить ошибку, с которой столкнулся Ansible. Рассмотрим пример плейбука, в котором определена переменная var1, но в задаче по ошибке используется неопределенная переменная wrong_var.

- hosts: test
  debugger: on_failed
  gather_facts: no
  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 приведет к успешному выполнению задачи.

Доступные команды отладки

В командной строке отладки вы можете использовать следующие семь команд:

Для более подробной информации см. индивидуальные описания и примеры ниже.

Команда print

print *task/task.args/task_vars/host/result* выводит информацию о задаче:

[192.0.2.10] TASK: install package (debug)> p task
TASK: install package
[192.0.2.10] TASK: install package (debug)> p task.args
{u'name': u'{{ pkg_name }}'}
[192.0.2.10] TASK: install package (debug)> p task_vars
{u'ansible_all_ipv4_addresses': [u'192.0.2.10'],
 u'ansible_architecture': u'x86_64',
 ...
}
[192.0.2.10] TASK: install package (debug)> p task_vars['pkg_name']
u'bash'
[192.0.2.10] TASK: install package (debug)> p host
192.0.2.10
[192.0.2.10] TASK: install package (debug)> p result._result
{'_ansible_no_log': False,
 'changed': False,
 u'failed': True,
 ...
 u'msg': u"No package matching 'not_exist' is available"}

Команда обновления аргументов

task.args[*key*] = *value* обновляет аргумент модуля. В этом примере плейбука неверно указано имя пакета:

- hosts: test
  strategy: debug
  gather_facts: yes
  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 для повторного выполнения задачи.

Команда обновления задачи

u или update_task пересоздаёт задачу из исходной структуры данных задачи и шаблонов с обновлёнными переменными задачи. Смотрите запись Команда обновления переменных для примера использования.

Команда повторного выполнения

r или redo выполняет задачу повторно.

Команда продолжения

c или continue продолжает выполнение, начиная со следующей задачи.

Команда выхода

q или quit завершает работу отладчика. Выполнение плейбука прерывается.

Как отладчик взаимодействует со стратегией свободного выполнения

При использовании стратегии linear, Ansible приостанавливает выполнение, пока отладчик активен, и выполняет отлаживаемое задание сразу после ввода команды redo. Однако, при включенной стратегии free, Ansible не ожидает всех хостов и может поместить последующие задачи в очередь на одном хосте, прежде чем на другом хосте выполнение задачи завершится ошибкой. При использовании стратегии free, Ansible не помещает задачи в очередь и не выполняет их, пока отладчик активен. Однако все задачи в очереди остаются в очереди и выполняются сразу после выхода из отладчика. Если вы используете redo, чтобы перепланировать задание из отладчика, другие задачи в очереди могут быть выполнены до перепланированной задачи. Для получения дополнительной информации о стратегиях, см. Управление выполнением playbook: стратегии и многое другое.