Uso da Diretiva when

A diretiva when permite que tarefas sejam executadas apenas quando uma condição especificada é verdadeira. Por padrão, para referenciar variáveis definidas no playbook, não é necesssário usar chaves duplas {{}}, mas valores literais devem ser colocados entre aspas.

vars:
  sistema: debian11

when: sistema  # Variável definida, sem aspas

when: "'webserver' in group_names"  # Valor literal requer aspas simples dentro de aspas duplas

1. Expressões de Comparação

Operadores de Comparação

Operadores como == (igualdade), != (desigualdade), >=, <=, > e < podem ser usados para comparar strings ou números.

- hosts: servidores
  tasks:
    - debug:
        var: ansible_all_ipv4_addresses
      when: ansible_hostname == "servidor01"

Operadores Lógicos

Utilize and (e lógico), or (ou lógico), not (negação) e parênteses () para combinar expressões.

# Exemplo com 'and'
- debug:
    msg: Este é um sistema baseado em Debian
  when: ansible_distribution == "Debian" and ansible_distribution_version == "11"

# Exemplo com 'or'
- debug:
    msg: Condição atendida via hostname ou endereço IP
  when: inventory_hostname == "no-web" or ansible_eth0.ipv4.address == '10.0.0.5'

# Exemplo com 'not'
- debug:
    msg: Executado em hosts diferentes de no-web
  when: not inventory_hostname == "no-web"

Retorno de Código (rc)

Módulos de comando como shell ou command retornam um código de saída (rc). Módulos como file ou copy não possuem esse retorno. Use register para capturar o resultado.

- shell: ls /arquivo/inexistente
  register: resultado_comando
  ignore_errors: yes
- debug:
    msg: O comando foi bem-sucedido
  when: resultado_comando.rc == 0
- debug:
    msg: O comando falhou
  when: resultado_comando.rc != 0

Verificação de Caminhos no Sistema de Arquivos

Use testes como is file, is directory, is link, is mount e is exists para verificar propriedades de caminhos.

- debug:
    msg: O arquivo existe
  when: "'/etc/passwd' is exists"

# Alternativa usando variável
vars:
  caminho_config: /etc/app.conf
tasks:
  - debug:
      msg: Arquivo de configuração presente
    when: "caminho_config is file"

Verificação de Resultados de Tarefas

Ao registrar uma tarefa, é possível verificar seu estado com testes como is changed, is succeeded, is failed ou is skip. Note que tarefas ignoradas com ignore_errors podem aparecer como puladas, mas ainda são consideradas falhas.

- shell: ls /tmp/arquivo_temp
  register: status_temp
  ignore_errors: yes
- debug:
    msg: A tarefa foi pulada
  when: status_temp is skip

Verificação de Variáveis

Utilize is defined para verificar se uma variável foi definida, e is undefined caso contrário.

vars:
  param_opcional:
tasks:
  - debug:
      msg: Variável foi definida (mesmo sem valor)
    when: param_opcional is defined

Verificação de Tipos de Dados

Use is string e is number para verificar se uma variável é do tipo string ou número.

vars:
  versao: 12
tasks:
  - debug:
      msg: A versão é numérica
    when: versao is number

Verificação de Maiúsculas e Minúsculas

Testes como is lower e is upper verificam se uma string contém apenas letras minúsculas ou maiúsculas.

vars:
  nome_host: webservidor
tasks:
  - debug:
      msg: O hostname está em minúsculas
    when: nome_host is lower

Verificação de Paridade e Divisibilidade

Use is even, is odd e is divisibleby(n) para verificar números.

vars:
  quantidade: 20
tasks:
  - debug:
      msg: Quantidade é par e divisível por 4
    when: quantidade is even and quantidade is divisibleby(4)

Pertinência a Coleções

O teste in verifica se um item pertence a uma lista ou dicionário.

- debug:
    msg: Interface eth0 encontrada
  when: "'eth0' in ansible_interfaces"

2. Outras Diretivas Importantes

Blocos (block, rescue, always)

Agrupe múltiplas tarefas com block. Use rescue para tratar erros e always para tarefas que devem executar independentemente do resultado.

- hosts: servidores
  tasks:
    - block:
        - debug:
            msg: Início do bloco
        - shell: comando_complexo
      when: ansible_os_family == "Debian"
      rescue:
        - debug:
            msg: Erro tratado no bloco
      always:
        - debug:
            msg: Esta tarefa sempre executa

Parada Condicional com fail e failed_when

Use fail para interromper a execução ou failed_when em uma tarefa para definir condições de falha específicas.

- shell: verificacao_critica.sh
  register: check_result
  ignore_errors: yes
- fail:
    msg: Verificação crítica falhou. Abortando playbook.
  when: check_result.rc != 0
- debug:
    msg: Esta tarefa só executa se a verificação passar.

Estruturas de Repetição

1. with_items

Percorre uma lista, atribuindo cada elemento à variável item.

vars:
  usuarios:
    - ana
    - bruno
    - carlos
tasks:
  - debug:
      msg: "{{ item }}"
    with_items: "{{ usuarios }}"

# Forma alternativa inline
- debug:
    msg: "{{ item }}"
  with_items:
    - ana
    - bruno
    - carlos

2. with_dict

Percorre um dicionário, onde cada iteração fornece item.key e item.value.

vars:
  perfis:
    admin:
      uid: 1000
      nome: Ana Silva
    dev:
      uid: 1001
      nome: Bruno Costa
tasks:
  - debug:
      msg: "{{ item.key }}: {{ item.value.nome }}"
    with_dict: "{{ perfis }}"

3. loop

A forma moderna e recomendada. Para listas, itera diretamente. Para dicionários, use o filtro dict2items.

# Percorrendo lista
vars:
  pacotes:
    - nginx
    - postgresql
    - redis
tasks:
  - debug:
      msg: "Instalando {{ item }}"
    loop: "{{ pacotes }}"

# Percorrendo dicionário com filtro
vars:
  configuracoes:
    porta_http: 80
    porta_https: 443
tasks:
  - debug:
      msg: "{{ item.key }} está definida como {{ item.value }}"
    loop: "{{ configuracoes | dict2items }}"

# Usando filtro de hash de senha
vars:
  senha_plana: "minhasenha123"
tasks:
  - user:
      name: usuario_app
      password: "{{ senha_plana | password_hash('sha512') }}"