Обработка ошибок в плейбуках

• Игнорирование не удавшихся команд
• Сброс недоступных хостов
• Обработчики и ошибки
• Управление тем, что определяет ошибку
• Переопределение результата изменения
• Прерывание плейбука

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

Иногда команда, возвращающая значение отличное от 0, не является ошибкой. Иногда команде не всегда нужно сообщать, что она «изменила» удалённую систему. В этом разделе описывается, как изменить поведение Ansible по умолчанию для определённых задач, чтобы поведение вывода и обработки ошибок было желаемым.

Игнорирование не удавшихся команд

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

- name: this will not be counted as a failure
  command: /bin/false
  ignore_errors: yes

Обратите внимание, что вышеуказанная система управляет только значением возврата ошибки конкретной задачи, поэтому, если используется неопределённая переменная или синтаксическая ошибка, будет всё равно генерироваться ошибка, которую пользователи должны будут обработать. Обратите внимание, что это не предотвратит ошибки при подключении или выполнении. Эта функция работает только тогда, когда задача должна быть выполнена и вернуть значение «failed».

Сброс недоступных хостов

Ошибки подключения устанавливают хосты как «НЕДОСТУПНЫЕ», что удалит их из списка активных хостов для выполнения. Чтобы восстановиться после этих проблем, вы можете использовать meta: clear_host_errors для повторной активации всех помеченных хостов, чтобы последующие задачи могли снова использовать их.

Обработчики и ошибки

Когда задача завершается с ошибкой на хосте, обработчики, которые были ранее уведомлены, не будут запущены на этом хосте. Это может привести к случаям, когда независящая ошибка может оставить хост в неожиданном состоянии. Например, задача может обновить конфигурационный файл и уведомить обработчик о перезапуске некоторой службы. Если впоследствии в том же плейбуке завершится ошибкой какая-то задача, служба не будет перезапущена, несмотря на изменение конфигурации.

Вы можете изменить это поведение с помощью команды --force-handlers параметр командной строки или включив force_handlers: True в плейбук, или force_handlers = True в ansible.cfg. Когда обработчики принудительно запускаются, они будут выполняться при уведомлении, даже если задача завершится ошибкой на данном хосте. (Обратите внимание, что некоторые ошибки всё ещё могут помешать запуску обработчика, например, если хост станет недоступным.)

Управление тем, что определяет ошибку

Предположим, что код ошибки команды бессмысленный, и чтобы определить наличие ошибки, важен вывод команды, например, если в выводе присутствует строка «FAILED».

Ansible предоставляет способ указать это поведение следующим образом:

- name: Fail task when the command error output prints FAILED
  command: /usr/bin/example-command -x -y -z
  register: command_result
  failed_when: "'FAILED' in command_result.stderr"

или на основе кода возврата:

- name: Fail task when both files are identical
  raw: diff foo/file1 bar/file2
  register: diff_cmd
  failed_when: diff_cmd.rc == 0 or diff_cmd.rc >= 2

В предыдущих версиях Ansible это можно было сделать следующим образом:

- name: this command prints FAILED when it fails
  command: /usr/bin/example-command -x -y -z
  register: command_result
  ignore_errors: True

- name: fail the play if the previous command did not succeed
  fail:
    msg: "the command failed"
  when: "'FAILED' in command_result.stderr"

Переопределение результата изменения

При выполнении оболочки/команды или другого модуля, как правило, сообщается статус «изменено» в зависимости от того, полагает ли он, что он повлиял на состояние машины.

Иногда, исходя из кода возврата или вывода, вы знаете, что изменений не было, и хотите переопределить результат «изменено», чтобы он не отображался в выходных данных отчёта или не вызывал обработчики:

tasks:

  - shell: /usr/bin/billybass --mode="take me to the river"
    register: bass_result
    changed_when: "bass_result.rc != 2"

  # this will never report 'changed' status
  - shell: wall 'beep'
    changed_when: False

Прерывание плейбука

Иногда желательно прервать весь плейбук при возникновении ошибки, а не просто пропустить оставшиеся задачи для хоста.

Параметр плейбука any_errors_fatal пометит все хосты как завершённые с ошибкой, если какая-либо задача завершится ошибкой, вызвав немедленное прерывание:

- hosts: somehosts
  any_errors_fatal: true
  roles:
    - myrole

для более тонкого управления можно использовать max_fail_percentage для прерывания выполнения после того, как определённый процент хостов завершится с ошибкой.