Ansible обработка ошибок

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

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

• Игнорирование неудачных команд
• игнорирование недоступных ошибок хоста
• Сброс недоступных хостов
• Дескрипторы и отказ
• Defining failure
• Defining “changed”
• Обеспечение успеха для командования и снаряда

• Прерывание игры на всех хозяевах

  • Прерывание первой ошибки:any_errors_fatal
  • Установка максимального процента отказа
• Ошибки управления блоками

Игнорирование неудачных команд

По умолчанию Ansible прекращает выполнение задач на хосте при сбое задачи на этом хосте. Вы можете использовать ignore_errors , чтобы продолжить несмотря на сбой:

- name: Do not count this as a failure
  ansible.builtin.command: /bin/false
  ignore_errors: yes

Директива ignore_errors работает только тогда, когда задача может быть запущена и возвращает значение «сбой». Это не заставляет Ansible игнорировать ошибки неопределенных переменных, сбои соединения, проблемы с выполнением (например, отсутствующие пакеты) или синтаксические ошибки.

игнорирование недоступных ошибок хоста

Новинка в версии 2.7.

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

- name: This executes, fails, and the failure is ignored
  ansible.builtin.command: /bin/true
  ignore_unreachable: yes

- name: This executes, fails, and ends the play for this host
  ansible.builtin.command: /bin/true

И на игровом уровне:

- hosts: all
  ignore_unreachable: yes
  tasks:
  - name: This executes, fails, and the failure is ignored
    ansible.builtin.command: /bin/true

  - name: This executes, fails, and ends the play for this host
    ansible.builtin.command: /bin/true
    ignore_unreachable: no

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

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

Дескрипторы и отказ

Ansible runs handlers at the end of each play. If a task notifies a handler but another task fails later in the play, by default the handler does not run on that host, which may leave the host in an unexpected state. For example, a task could update a configuration file and notify a handler to restart some service. If a task later in the same play fails, the configuration file might be changed but the service will not be restarted.

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

Defining failure

Ansible позволяет определить, что означает «сбой» в каждой задаче, используя условие failed_when . Как и все условные операторы в Ansible, списки нескольких условий failed_when объединяются неявным оператором and , что означает, что задача завершается сбоем только при соблюдении всех условий. Если вы хотите инициировать сбой при выполнении любого из условий, вы должны определить условия в строке с явным оператором or .

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

- name: Fail task when the command error output prints FAILED
  ansible.builtin.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
  ansible.builtin.raw: diff foo/file1 bar/file2
  register: diff_cmd
  failed_when: diff_cmd.rc == 0 or diff_cmd.rc >= 2

Вы также можете комбинировать несколько условий для отказа.Эта задача будет неудачной,если оба условия верны:

- name: Check if a file exists in temp and fail task if it does
  ansible.builtin.command: ls /tmp/this_should_not_be_here
  register: result
  failed_when:
    - result.rc == 0
    - '"No such" not in result.stdout'

Если вы хотите, чтобы задача не выполнялась при выполнении только одного условия, измените определение failed_when на:

failed_when: result.rc == 0 or "No such" not in result.stdout

Если у вас слишком много условий для аккуратного размещения в одной строке, вы можете разделить его на многострочное значение yaml с помощью > :

- name: example of many failed_when conditions with OR
  ansible.builtin.shell: "./myBinary"
  register: ret
  failed_when: >
    ("No such file or directory" in ret.stdout) or
    (ret.stderr != '') or
    (ret.rc == 10)

Defining “changed”

Ansible позволяет вам определить, когда конкретная задача «изменила» удаленный узел, используя условное changed_when . Это позволяет вам определить, на основе кодов возврата или вывода, следует ли сообщать об изменении в статистике Ansible и должен ли запускаться обработчик или нет. Как и все условные операторы в Ansible, списки нескольких условий changed_when объединяются неявным оператором and , что означает, что задача сообщает об изменении только тогда, когда все условия соблюдены. Если вы хотите сообщить об изменении при выполнении любого из условий, вы должны определить условия в строке с явным оператором or .Например:

tasks:

  - name: Report 'changed' when the return code is not equal to 2
    ansible.builtin.shell: /usr/bin/billybass --mode="take me to the river"
    register: bass_result
    changed_when: "bass_result.rc != 2"

  - name: This will never report 'changed' status
    ansible.builtin.shell: wall 'beep'
    changed_when: False

Вы также можете объединить несколько условий,чтобы отменить результат «изменено»:

- name: Combine multiple conditions to override 'changed' result
  ansible.builtin.command: /bin/fake_command
  register: result
  ignore_errors: True
  changed_when:
    - '"ERROR" in result.stderr'
    - result.rc == 2

Дополнительные примеры условного синтаксиса см. В разделе Определение ошибки .

Обеспечение успеха для командования и снаряда

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

tasks:
  - name: Run this command and ignore the result
    ansible.builtin.shell: /usr/bin/somecommand || /bin/true

Прерывание игры на всех хозяевах

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

Прерывание первой ошибки:any_errors_fatal

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

- hosts: somehosts
  any_errors_fatal: true
  roles:
    - myrole

- hosts: somehosts
  tasks:
    - block:
        - include_tasks: mytasks.yml
      any_errors_fatal: true

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

---
- hosts: load_balancers_dc_a
  any_errors_fatal: true

  tasks:
    - name: Shut down datacenter 'A'
      ansible.builtin.command: /usr/bin/disable-dc

- hosts: frontends_dc_a

  tasks:
    - name: Stop service
      ansible.builtin.command: /usr/bin/stop-software

    - name: Update software
      ansible.builtin.command: /usr/bin/upgrade-software

- hosts: load_balancers_dc_a

  tasks:
    - name: Start datacenter 'A'
      ansible.builtin.command: /usr/bin/enable-dc

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

Установка максимального процента отказа

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

---
- hosts: webservers
  max_fail_percentage: 30
  serial: 10

Параметр max_fail_percentage применяется к каждому пакету, когда вы используете его с последовательным интерфейсом . В приведенном выше примере, если более 3 из 10 серверов в первой (или любой) группе серверов вышли из строя, остальная часть игры будет прервана.

Ошибки управления блоками

Вы также можете использовать блоки для определения ответов на ошибки задачи. Этот подход похож на обработку исключений во многих языках программирования. См. Подробности и примеры в разделе Обработка ошибок с помощью блоков .

Ansible

• Контроль над тем,где выполняются задачи:делегирование и местные действия.

  По умолчанию Ansible собирает факты и выполняет все задачи на машинах, которые соответствуют строке hosts из вашего playbook.

• Настройка удаленной среды

  Новое в версии 1.1.

• Использование фильтров для манипулирования данными

  Фильтры позволяют преобразовывать данные JSON в разделенный URL-адрес YAML, извлекать имя хоста, получать хэш строки SHA1, добавлять несколько целых чисел и многое другое.

• Объединение и выбор данных

  Вы можете комбинировать данные из нескольких источников и типов, выбирать значения больших структур, предоставляя точный контроль над комплексом Новое в версии 2.3.

Have you ever gotten to the end of your Ansible Playbook execution and found you needed to:

1. Rescue from errors or partial execution of your tasks
2. Capture a summary of the results per host for further revision

If you have Ansible Automation Platform (AAP), you can use the techniques I described in How to use workflow job templates in Ansible to handle #1, and you will need something like the set_stats module for #2 (to be able to persist variables between workflow nodes).

In this article, I will cover the block/rescue feature in Ansible. You can incorporate it into your playbooks, whether or not you have AAP. You can then take these playbooks and run then in your AAP instance.

[ Compare Ansible vs. Red Hat Ansible Automation Platform. ]

By learning this new technique, you can use the approach that suits you best.

What is a block?

A block is a logical grouping of tasks within a playbook that can be executed as a single unit. This makes it easy to manage complex playbooks by breaking them down into smaller, more manageable parts.

You can use blocks to apply options to a group of tasks and avoid repeating code, like in this example from the documentation.

 tasks:
   - name: Install, configure, and start Apache
     block:
       - name: Install httpd and memcached
         ansible.builtin.yum:
           name:
           - httpd
           - memcached
           state: present

       - name: Apply the foo config template
         ansible.builtin.template:
           src: templates/src.j2
           dest: /etc/foo.conf

       - name: Start service bar and enable it
         ansible.builtin.service:
           name: bar
           state: started
           enabled: True
     when: ansible_facts['distribution'] == 'CentOS'
     become: true
     become_user: root
     ignore_errors: true

Notice that the keywords when, become, become_user, and ignore_errors are all applied to the block.

[ Write your first Ansible Playbook in this hands-on interactive lab. ]

How to use blocks and rescue in Ansible

Blocks and rescue work together to provide error-handling capabilities in Ansible. Use the rescue keyword in association with a block to define a set of tasks that will be executed if an error occurs in the block. You can use the rescue tasks to handle errors, log messages, or take other actions to recover from the error.

Here is a high-level example:

---
- hosts: <hosts>
  tasks:
    - block:
        - <task1>
        - <task2>
        - <task3>
      rescue:
        - <rescue_task1>
        - <rescue_task2>
        - <rescue_task3>
      always:
        - <always_task>

You define tasks under the block keyword, which could be as simple as invoking the ansible.builtin.ping module, or you could have a combination of multiple tasks and including/importing roles.

The associated rescue keyword is where the playbook execution will be sent, for each host, if anything fails along the block.

Finally, the always section executes for all nodes, no matter if they succeed or fail.

Some key ideas from this structure:

1. rescue and always are optional features, which I will use for the specific purpose of demonstrating this «recover and summary» logic.
2. When your playbook runs against a considerable number of hosts, handling the individual results becomes harder to track. This is how the ideas discussed in this article can help.

For the following example, the inventory file contains:

[nodes]
node1
node2
node3

Here is the playbook:

---
- name: Test block/rescue
  hosts: nodes
  gather_facts: false

  tasks:

    - name: Main block
      block:
        - name: Role 1
          ansible.builtin.include_role:
            name: role1

        - name: Role 2
          ansible.builtin.include_role:
            name: role2

        - name: Accumulate success
          ansible.builtin.set_fact:
            _result:
              host: "{{ inventory_hostname }}"
              status: "OK"
              interfaces: "{{ ansible_facts['interfaces'] }}"

      rescue:
        - name: Accumulate failure
          ansible.builtin.set_fact:
            _result:
              host: "{{ inventory_hostname }}"
              status: "FAIL"

      always:
        - name: Tasks that will always run after the main block
          block:
            - name: Collect results
              ansible.builtin.set_fact:
                _global_result: "{{ (_global_result | default([])) + [hostvars[item]['_result']] }}"
              loop: "{{ ansible_play_hosts }}"

            - name: Classify results
              ansible.builtin.set_fact:
                _result_ok: "{{ _global_result | selectattr('status', 'equalto', 'OK') | list }}"
                _result_fail: "{{ _global_result | selectattr('status', 'equalto', 'FAIL') | list }}"

            - name: Display results OK
              ansible.builtin.debug:
                msg: "{{ _result_ok }}"
              when: (_result_ok | length ) > 0

            - name: Display results FAIL
              ansible.builtin.debug:
                msg: "{{ _result_fail }}"
              when: (_result_fail | length ) > 0
          delegate_to: localhost
          run_once: true
...

Think about this playbook as an illustration of some logic that could be applied to a complex automation in the real world. Yes, you could run simpler actions to recover or issue a notification about the failure, but you want a summary of all results. Then you can use this summary in the always section to automate sending a notification by email or writing the individual results into a database.

Also, the variables starting with _ are my personal naming convention preference… there’s no special meaning in Ansible for that.

1. For this example, the roles in the main block don’t do anything special. They represent the actions that you would put in the main block, which could fail at different points. In this simplified example, if a node succeeds, there will be a list of interfaces in the _result variable. Otherwise, the status will be set to FAIL.
2. For each host the playbook is running on:
   1. If the actions proceed without errors, the task Accumulate success will execute.
   2. If the action fails in any of the roles, the flow goes to the rescue block for each host.
3. The always section collects the results saved in the variable _result. Here is a little breakdown of the logic:
   1. Up to this point, each host has a variable in its hostvars structure, either with a success or failed status information.
   2. In the Collect results task, which runs once and is delegated to localhost, it captures the individual results and adds them to the list _global_result.
   3. The loop is done using the Ansible magic variable ansible_play_hosts_all, which is a list of all hosts targeted by this playbook.
   4. Classify results does some filtering to create a list of all OK and failed results. You can use these in notifications, reports, or to send to a database (this example just displays them).

If you run this playbook and no node fails, there is no need for rescue, and the display should show that results are OK in all nodes:

PLAY [Test block/rescue] *******************************************************

TASK [Role 1] ******************************************************************

TASK [role1 : Execution of role 1] *********************************************
ok: [node1] => {
    "changed": false,
    "msg": "All assertions passed"
}
ok: [node2] => {
    "changed": false,
    "msg": "All assertions passed"
}
ok: [node3] => {
    "changed": false,
    "msg": "All assertions passed"
}

TASK [Role 2] ******************************************************************

TASK [role2 : Execution of role 2] *********************************************
ok: [node1]
ok: [node2]
ok: [node3]

TASK [role2 : Show network information] ****************************************
skipping: [node1]
skipping: [node2]
skipping: [node3]

TASK [Accumulate success] ******************************************************
ok: [node1]
ok: [node2]
ok: [node3]

TASK [Collect results] *********************************************************
ok: [node1 -> localhost] => (item=node1)
ok: [node1 -> localhost] => (item=node2)
ok: [node1 -> localhost] => (item=node3)

TASK [Classify results] ********************************************************
ok: [node1 -> localhost]

TASK [Display results OK] ******************************************************
ok: [node1 -> localhost] => {
    "msg": [
        {
            "host": "node1",
            "interfaces": [
                "lo",
                "enp7s0",
                "enp1s0"
            ],
            "status": "OK"
        },
        {
            "host": "node2",
            "interfaces": [
                "lo",
                "enp7s0",
                "enp1s0"
            ],
            "status": "OK"
        },
        {
            "host": "node3",
            "interfaces": [
                "enp7s0",
                "lo",
                "enp1s0"
            ],
            "status": "OK"
        }
    ]
}

TASK [Display results FAIL] ****************************************************
skipping: [node1]

PLAY RECAP *********************************************************************
node1   : ok=6    changed=0    unreachable=0    failed=0    skipped=2    rescued=0    ignored=0   
node2   : ok=3    changed=0    unreachable=0    failed=0    skipped=1    rescued=0    ignored=0   
node3   : ok=3    changed=0    unreachable=0    failed=0    skipped=1    rescued=0    ignored=0   

If you force a failure in some nodes, they will invoke the rescue section, and the summary will show the ones that succeeded and those that failed:

PLAY [Test block/rescue] *******************************************************

TASK [Role 1] ******************************************************************

TASK [role1 : Execution of role 1] *********************************************
ok: [node1] => {
    "changed": false,
    "msg": "All assertions passed"
}
fatal: [node2]: FAILED! => {
    "assertion": "inventory_hostname in nodes_ok",
    "changed": false,
    "evaluated_to": false,
    "msg": "Assertion failed"
}
fatal: [node3]: FAILED! => {
    "assertion": "inventory_hostname in nodes_ok",
    "changed": false,
    "evaluated_to": false,
    "msg": "Assertion failed"
}

TASK [Role 2] ******************************************************************

TASK [role2 : Execution of role 2] *********************************************
ok: [node1]

TASK [role2 : Show network information] ****************************************
skipping: [node1]

TASK [Accumulate success] ******************************************************
ok: [node1]

TASK [Accumulate failure] ******************************************************
ok: [node2]
ok: [node3]

TASK [Collect results] *********************************************************
ok: [node1 -> localhost] => (item=node1)
ok: [node1 -> localhost] => (item=node2)
ok: [node1 -> localhost] => (item=node3)

TASK [Classify results] ********************************************************
ok: [node1 -> localhost]

TASK [Display results OK] ******************************************************
ok: [node1 -> localhost] => {
    "msg": [
        {
            "host": "node1",
            "interfaces": [
                "enp7s0",
                "enp1s0",
                "lo"
            ],
            "status": "OK"
        }
    ]
}

TASK [Display results FAIL] ****************************************************
ok: [node1 -> localhost] => {
    "msg": [
        {
            "host": "node2",
            "status": "FAIL"
        },
        {
            "host": "node3",
            "status": "FAIL"
        }
    ]
}

PLAY RECAP *********************************************************************
node1   : ok=7    changed=0    unreachable=0    failed=0    skipped=1    rescued=0    ignored=0   
node2   : ok=1    changed=0    unreachable=0    failed=0    skipped=0    rescued=1    ignored=0   
node3   : ok=1    changed=0    unreachable=0    failed=0    skipped=0    rescued=1    ignored=0   

Notice that even though there were failures, at the end, the Ansible output counts them as rescued.

[ Get started with automation controller in this hands-on interactive lab. ]

Handle exceptions

I hope this article has given you some ideas about how to handle exceptions in your playbooks.

You can also think about what actions you want in your rescue section, such as displaying a message or performing some «undo» action, depending on what stage it reached before the failure.

Finally, you can execute the always section for each host or, as in my example, one time only.