ANSIBLE SERIES: h.t.wrt* … tasks, plays e books: failures! (or error handling)

De tempos em tempos, a humanidade é testemunha de um curioso, engraçado e certo tipo de evento: erros que se transformam em felizes acertos! Não faz sentido pra você? Tudo bem, sem problemas! Eu lhe apresento 🥁🥁🥁 a penicilina e a coca-cola 🤭 rsrs! Então, voltando … O mesmo pode acontecer no Ansible. Eventualmente, um código de retorno com valor não-zero (diferente de zero), seja vindo de um comando ou de uma falha em determinado módulo, pode ser exatamente o que você busca no momento e por isso, não vai querer que o Ansible pare a execução naquele host e siga para o próximo. Não, muito pelo contrário. Tal código não-zero indica para você, e sua demanda/tarefa, um verdadeiro baita de um sucesso! Portanto, nada mais lógico do que tratá-lo … Correto? Bom, antes de iniciar os trabalhos, um exemplo básico de situação hipotética para ilustrar melhor: numa bela e ensolarada manhã, seu chefe propõe a você que, caso um host apresente uma falha, o Ansible pare/encerre instantaneamente a execução em todos os outros. Fim!

Agora sim, adiante! Vamos a aula de hoje, com o seu respectivo sumário listado a seguir:

  • Ignorando comandos com falha;
  • Ignorando erros de host inacessíveis;
  • Redefinindo hosts inacessíveis;
  • Manipuladores e falha;
  • Definindo falha;
  • Definindo “alterado”;
  • Garantindo o sucesso para o comando e shell;
  • Abortando uma reprodução em todos os hosts;
  • Controle de erros em blocos;

07-a. Ignorando comandos com falhas

O comportamento padrão, quando uma task qualquer falha num host particular, é puro e simplesmente parar a execução das outras tarefas no mesmo, não importando a quantidade que faltava ou em qual task ele estava (ex: a primeira, a do meio, ou a última). Dessa forma, o Ansible pularia para o próximo host sem piscar duas vezes. Contudo, é totalmente possível continuar naquele host específico apesar dos apesares, ou melhor dizendo, da(s) falha(s). Basta utilizar a palavra-chave ignore_errors:

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

Mas, atenção aqui! Tenha cuidado! Pois essa regra somente funcionará com tarefas capazes de retornar o valor 'failed' (“falhou”). Sendo assim, o Ansible jamais/nunca ignora erros de: variáveis indefinidas, falhas de conexão, problemas de execução, pacotes ausentes ou até mesmo erros de sintaxe.

07-b. Ignorando erros de hosts inacessíveis

Em sua jornada diária, quantas e quantas vezes aquele seu colega sysadmin da infra/operação moveu uma VM de lugar, acrescentou uma nova regra de firewall, ou desligou um grupo de máquinas sem nenhum aviso prévio? Eu sei, talvez sua resposta seja: muitas, várias vezes … Certo? 😥 Mas calma! Por favor, peço que não brigue com ele! Afinal o dia-a-dia de um admin/ops pode ser um pouco cheio e meio estressante, de tanto deveres, rotinas e tarefas. E por isso, eis que trago a solução para os seus problemas (ou erros, neste caso). Se uma task abortar dado ao status do host ser ‘UNREACHABLE’, use ignore_unreachable. Assim o Ansible ignora os erros da tarefa atual, mas permanecendo disponível para executar eventuais futuras tarefas no host que está inacessível no momento 🤩

À nível de task:

- 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

À nível de playbook:

- 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

07-c. Redefinindo hosts inacessíveis

Se o Ansible não puder se conectar a um host, ele marca esse host como ‘UNREACHABLE’ e o remove da lista de hosts ativos para a execução. Você pode usar meta: clear_host_errors para reativar todos os hosts, para que as tarefas subsequentes possam tentar alcançá-los novamente. ( Top demais! 👌💯 )

07-d. Manipuladores e falhas

Ansible executa handlers no final de cada play … Desde a nossa aula passada isso já é fato conhecido! PORÉM, e se uma tarefa notifica um manipulador, mas aí vem uma falha e faz o mesmo, logo em seguida ou posteriormente, na execução do playbook? O que acontece? Bem, o esperado e padrão é o manipulador não ser executado naquele host, o que pode deixar o host em um estado inesperado. Por exemplo, uma tarefa pode atualizar um arquivo de configuração e notificar um manipulador para reiniciar algum serviço. Se uma tarefa posterior na mesma execução falhar, o arquivo de configuração pode ser alterado, mas o serviço não será reiniciado.

Para evitar, reverter ou burlar (nomeie como quiser!) tal comportamento basta usar a opção de linha de comando --force-handlers, incluindo force_handlers: True em uma play, ou adicionando force_handlers = True ao ansible.cfg. Quando os manipuladores são forçados, o Ansible executará todos os manipuladores notificados em todos os hosts, até mesmo hosts com tarefas com falha. (Observe que certos erros ainda podem impedir a execução do handler, como um host inacessível.)

07-e. Definindo uma falha

O Ansible permite definir o que “falha” significa em cada tarefa usando a condição failed_when. Como acontece nas outras condicionais do Ansible, listas com várias condições failed_when são unidas com um and implícito, o que refletindo na tarefa em si, já que a mesma só falha quando todas as condições são atendidas. Caso deseje o oposto disso, que é uma “falha” quando qualquer uma das condições for atendida, você deve definir as condições em uma string com um operador oR explícito.

Você pode verificar se há falhas pesquisando uma palavra ou frase na saída de um comando:

- 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"

Ou baseado no código de retorno:

- 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

+ 1 exemplo: combinar múltiplas condições para definir uma “falha”

- 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'

07-f. Definindo “alterado”

O Ansible permite definir quando uma tarefa específica “mudou” um nó remoto usando a condição changed_when. Isso permite determinar, com base em códigos de retorno ou saída, se uma alteração deve ser relatada nas estatísticas Ansible e se um manipulador deve ser acionado ou não. Como acontece com todas as condicionais em Ansible, listas de várias condições changed_when são unidas com um AND implícito, o que significa que a tarefa só relata uma mudança quando todas as condições são atendidas. Se quiser relatar uma mudança quando qualquer uma das condições for atendida, você deve definir as condições em uma string com um operador OR explícito. Por exemplo:

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

07-g. Garantindo o sucesso para o comando e shell

Os módulos de comando e shell se preocupam com os códigos de retorno, portanto, se você tiver um comando cujo código de saída bem-sucedido não seja zero, você pode fazer o seguinte:

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

07-h. Abortando uma execução em todos os hosts

Às vezes, você deseja que uma falha em um único host, ou falhas em uma certa porcentagem de hosts, aborte a execução inteira em todos os hosts. Você pode interromper a execução da reprodução após a primeira falha acontecer com any_errors_fatal. Para um controle mais refinado, você pode usar max_fail_percentage para abortar a execução após uma determinada porcentagem de hosts falhar.

07-i. Controle de erros em blocos

Veja detalhes e exemplos em https://docs.ansible.com/ansible/latest/user_guide/playbooks_blocks.html#block-error-handling

REFERÊNCIAS:

https://docs.ansible.com/ansible/latest/user_guide/playbooks_error_handling.html#playbooks-error-handling

ANSIBLE SERIES: h.t.wrt* … tasks, plays e books: handlers

CONT. 🔝

🔙 ANTERIOR: BLOCKS

Visto no final do post passado, numa breve participação coadjuvante, e já tendo aparecido em outras oportunidades aqui no BLOG, chegou a hora de conhecer um pouco mais sobre os handlers (traduzindo para o português: manipuladores). Objetiva e diretamente, são um tipo de tarefa que apenas se auto executa quando recebe uma notificação. Por exemplo, reiniciar determinado serviço (daemon) se, e somente se, alguma task modificou sua configuração. Em oposição, não fazer absolutamente nada enquanto tal permanecer inalterada. Outro fato importante, e assim como as variáveis, cada handler precisa ser nomeado exclusivamente.

  • Exemplo;
  • Controlando a execução de um handler (WHEN);
  • Usando variáveis com handlers;

06-a. Handler Example

A seguir, o playbook verify-apache.yml, apresentando uma play com handler simples:

---
- name: Verify apache installation
  hosts: webservers
  vars:
    http_port: 80
    max_clients: 200
  remote_user: root
  tasks:
  - name: Ensure apache is at the latest version
    ansible.builtin.yum:
      name: httpd
      state: latest

  - name: Write the apache config file
    ansible.builtin.template:
      src: /srv/httpd.j2
      dest: /etc/httpd.conf
    notify:
    - Restart apache

  - name: Ensure apache is running
    ansible.builtin.service:
      name: httpd
      state: started

  handlers:
    - name: Restart apache
      ansible.builtin.service:
        name: httpd
        state: restarted

Continuando, mais um playbook. Entretanto, agora é a vez de uma task (anteriormente foi uma play) ser responsável por notificar. Serve para demonstrar que uma única task é capaz de notificar mais de um handler simultaneamente:

- name: Template configuration file
  ansible.builtin.template:
    src: template.j2
    dest: /etc/foo.conf
  notify:
    - Restart memcached
    - Restart apache

  handlers:
    - name: Restart memcached
      ansible.builtin.service:
        name: memcached
        state: restarted

    - name: Restart apache
      ansible.builtin.service:
        name: apache
        state: restarted

06-b. Controlando a execução de um handler (WHEN)

Devido a sua concepção, manipuladores são executados depois que todas as tarefas em uma determinada play foram concluídas. Tal método é eficiente pois o manipulador é executado apenas uma vez, independentemente de quantas tarefas o notificam. Por exemplo, se várias tarefas atualizam um arquivo de configuração e notificam um manipulador para reiniciar o Apache, o Ansible pula o Apache apenas uma vez para evitar reinicializações desnecessárias.

Caso necessite que os handlers sejam executados bem antes do final da execução, basta adicionar uma task que os liberte para tal. Faça uso do ‘meta module’ presente no ansible-base, chamando-o para que o Ansible execute ações:

tasks:
  - name: Some tasks go here
    ansible.builtin.shell: ...

  - name: Flush handlers
    meta:flush_handlers

  - name: Some other tasks
    ansible.builtin.shell: ...

A tarefa meta: flush_handlers aciona todos os manipuladores que foram notificados naquele ponto da play em específico.

06-c. Usando variáveis com handlers

Talvez queira que seus manipuladores usem variáveis. Por exemplo, se o nome de um serviço variar ligeiramente de distro para distro, você espera que sua saída mostre o nome exato do serviço reiniciado para cada máquina de destino. Por isso, evite colocar variáveis no nome do manipulador. Como os nomes do manipulador são modelados desde o início, o Ansible pode não ter um valor disponível para um nome como este aqui:

handlers:
# This handler name may cause your play to fail!
- name: Restart "{{ web_service_name }}"

Se a variável usada no nome do manipulador não estiver disponível, toda a execução falhará. E antes que pense, não! Alterar essa variável “durante” não resultará em um manipulador recém-criado.

Em vez disso, coloque variáveis nos parâmetros de tarefa de seu manipulador. Você pode carregar os valores usando include_vars como este:

tasks:
  - name: Set host variables based on distribution
    include_vars: "{{ ansible_facts.distribution }}.yml"

handlers:
  - name: Restart web service
    ansible.builtin.service:
      name: "{{ web_service_name | default('httpd') }}"
      state: restarted

Os manipuladores também podem “ouvir” tópicos genéricos e as tarefas podem notificar esses tópicos da seguinte maneira:

handlers:
  - name: Restart memcached
    ansible.builtin.service:
      name: memcached
      state: restarted
    listen: "restart web services"

  - name: Restart apache
    ansible.builtin.service:
      name: apache
      state: restarted
    listen: "restart web services"

tasks:
  - name: Restart everything
    ansible.builtin.command: echo "this task will restart the web services"
    notify: "restart web services"

Isso torna muito mais fácil acionar vários manipuladores. Ele também desacopla os manipuladores de seus nomes, facilitando o compartilhamento de manipuladores entre playbooks e roles (especialmente ao usar funções de terceiros de uma fonte compartilhada como o Ansible Galaxy).

REFERÊNCIAS:

https://docs.ansible.com/ansible/latest/user_guide/playbooks_handlers.html#handlers

ANSIBLE SERIES: h.t.wrt* … tasks, plays e books: blocks

UPDATE! / DISCLAIMER: Depois de muitas idas e vindas ao banco … buscas e mais buscas à procura de documentos pessoais que não via há tanto tempo … cópias, xerox, pdf’s, assinaturas … e por fim, infinitas caixas/pacotes para organizar, mofo/poeira para limpar, caminhão da mudança, lavar o piso novo, desempacotar e remontar 😫😓 (…) Estou vivo, de volta e escrevendo da minha própria casa, cujo foi comprada em JUN/2021, também conhecido como ‘mês passado’. Esse foi o real motivo para o BLOG ter ficado tão parado nessas últimas semanas, caros e estimados leitores. Sendo assim, peço desculpas a todos! Espero que não fiquem chateados comigo 😥 MAS, é como dizem por aí: o show não pode parar! Então, retomando do ponto exato aonde paramos, a seguir, +1 capítulo da série ANSIBLE:

CONT. 🔝

🔙 ANTERIOR: CONDITIONALS

Analogamente (ou equivalente, se preferir) a um grupo de linhas dentro do código-fonte, blocos no contexto ‘ansible’ são formas/maneiras de lidar/tratar dois tipos de elemento básico: (a) tasks e (b) erros! Na prática, blocos acabam criando grupos lógicos, sejam micro tarefas que partilham determinado objetivo maior, sejam erros advindos de uma tarefa mal executada, displicentemente planejada. Em ambos os casos, podemos fazer um paralelo com o tratamento de exceções, observadas em outras linguagens de programação.

  • Agrupando tasks com blocos;
  • Tratando erros com blocos;

05-a. Agrupando tasks com blocos

A herança de dados, diretivas, ocorre e se aplica a todas as tarefas comuns (aninhadas) em um mesmo nível de bloco. Ou seja, a diretiva propriamente dita não afeta o bloco em si, mas sim as tasks delimitadas (contidas) por ele. Para exemplificar: uma vez validada e satisfeita a condição imposta pelo when, aplica-se a mesma numa única tacada para as diversas tarefas presentes no bloco em questão. O que é bem diferente de aplicar a ele mesmo, como pode ser levado a crer, e assim, induzido ao erro. A única exceção aqui são os loops. Esteja sempre atento!

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: yes

Resumidamente: a condição é avaliada ANTES e TODA VEZ que “alcançamos” um host diferente. Se passar, aí sim serão executadas as três tarefas informadas no bloco, para aquele node específico (e aprovado). O escalonamento e privilégio de root também são herdados, e por tabela, executados na sequência. Por fim, a última linha ignore_errors: yes serve apenas para que o Ansible dê continuidade ao playbook em casos de falhas nas tasks.

**Names for blocks have been available since Ansible 2.3. We recommend using names in all tasks, within blocks or elsewhere, for better visibility into the tasks being executed when you run the playbook.

05-b. Tratando erros com blocos

Trechos do código identificados como blocos, e marcados com as palavras rescue e always, são chamados (igualmente definidos) de sessões. Elas são peças-chave, fundamentais para controlar as respostas direcionadas a possíveis erros de tarefa.

Blocos rescue ditam novas tasks a serem executadas quando uma task anterior (do mesmo bloco) falhar. Tal abordagem é muito parecida com o tratamento de exceções presente em diversas outras linguagens de programação. É importante frisar aqui a seguinte informação: o Ansible somente executa blocos de resgate após uma tarefa retornar estado de FALHA (failed). Tasks definidas incorretamente ou hosts inacessíveis não irão disparar/acionar nenhum bloco de resgate.

tasks:
 - name: Handle the error
   block:
     - name: Print a message
       ansible.builtin.debug:
         msg: 'I execute normally'

     - name: Force a failure
       ansible.builtin.command: /bin/false

     - name: Never print this
       ansible.builtin.debug:
         msg: 'I never execute, due to the above task failing, :-('
   rescue:
     - name: Print when errors
       ansible.builtin.debug:
         msg: 'I caught an error, can do stuff here to fix it, :-)'

Dentro de um bloco também podem haver sessões always. A partir desse ponto, tarefas serão executadas independentemente do status anterior, ou seja, da task anterior.

- name: Always do X
   block:
     - name: Print a message
       ansible.builtin.debug:
         msg: 'I execute normally'

     - name: Force a failure
       ansible.builtin.command: /bin/false

     - name: Never print this
       ansible.builtin.debug:
         msg: 'I never execute :-('
   always:
     - name: Always do this
       ansible.builtin.debug:
         msg: "This always executes, :-)"

Misturados, esses dois fornecem um belo tratamento para erros um pouco mais complexos.

- name: Attempt and graceful roll back demo
  block:
    - name: Print a message
      ansible.builtin.debug:
        msg: 'I execute normally'

    - name: Force a failure
      ansible.builtin.command: /bin/false

    - name: Never print this
      ansible.builtin.debug:
        msg: 'I never execute, due to the above task failing, :-('
  rescue:
    - name: Print when errors
      ansible.builtin.debug:
        msg: 'I caught an error'

    - name: Force a failure in middle of recovery! >:-)
      ansible.builtin.command: /bin/false

    - name: Never print this
      ansible.builtin.debug:
        msg: 'I also never execute :-('
  always:
    - name: Always do this
      ansible.builtin.debug:
        msg: "This always executes"

As tarefas do bloco são executadas normalmente. Se alguma tarefa no bloco retornar failed, a seção de resgate executa tarefas para se recuperar do erro. A seção always é executada independentemente dos resultados das seções block e rescue.

Se ocorrer um erro no bloco e a tarefa de resgate for bem-sucedida, o Ansible reverterá o status de falha da tarefa original para a execução e continuará a executar a reprodução como se a tarefa original tivesse sido bem-sucedida. A tarefa resgatada é considerada bem-sucedida e não aciona configurações max_fail_percentage ou any_errors_fatal. No entanto, Ansible ainda relata uma falha nas estatísticas do playbook.

Use blocos com flush_handlers em uma tarefa de resgate para garantir que todos os manipuladores sejam executados mesmo se ocorrer um erro:

 tasks:
   - name: Attempt and graceful roll back demo
     block:
       - name: Print a message
         ansible.builtin.debug:
           msg: 'I execute normally'
         changed_when: yes
         notify: run me even after an error

       - name: Force a failure
         ansible.builtin.command: /bin/false
     rescue:
       - name: Make sure all handlers run
         meta: flush_handlers
 handlers:
    - name: Run me even after an error
      ansible.builtin.debug:
        msg: 'This handler runs even on error'

**New in version 2.1

**Ansible provides a couple of variables for tasks in the rescue portion of a block:

ansible_failed_task

The task that returned ‘failed’ and triggered the rescue. For example, to get the name use ansible_failed_task.name.

ansible_failed_result

The captured return result of the failed task that triggered the rescue. This would equate to having used this var in the register keyword.

REFERÊNCIAS:

https://docs.ansible.com/ansible/latest/user_guide/playbooks_blocks.html#playbooks-blocks