Guida Pratica al Debugging dei Moduli Shell e Command Falliti

I moduli command e shell di Ansible sono utili quando non esiste un modulo specifico, ma possono essere difficili da debuggare. Un task fallito potrebbe mostrare solo un codice di ritorno, a meno che non si catturi l'output del comando.

Questa guida mostra come debuggare i moduli shell e command falliti controllando rc, stdout e stderr, quindi utilizzando failed_when e changed_when per far sì che Ansible riporti il risultato reale.

---

Command vs. Shell: Comprendere la Differenza

Prima di immergersi nel debugging, è fondamentale comprendere la differenza fondamentale tra i due moduli, poiché il loro ambiente di esecuzione influisce sulle modalità di fallimento.

ansible.builtin.command

Questo modulo esegue il comando direttamente, bypassando l'ambiente shell standard. Ciò lo rende più sicuro e prevedibile, poiché evita funzionalità shell come interpolazione di variabili, globbing, pipe (|) e redirezione (>).

Buona Pratica: Usa command quando il task è semplice e non richiede funzionalità shell.

ansible.builtin.shell

Questo modulo esegue il comando tramite la shell standard dell'host remoto (/bin/sh o equivalente). È necessario per operazioni complesse, variabili d'ambiente o quando si utilizza la sintassi shell standard (es. cd /tmp && ls -l).

Attenzione: Poiché shell dipende dall'ambiente, è più soggetto a fallimenti imprevedibili legati alla configurazione del PATH, variabili d'ambiente nascoste o quoting complesso.

Anatomia di un Fallimento di un Comando Ansible

Per impostazione predefinita, Ansible determina il successo o il fallimento di un task dei moduli command o shell in base al codice di ritorno (RC) del processo.

Codice di Ritorno (RC)	Interpretazione
rc = 0	Successo (Il task continua)
rc != 0	Fallimento (Il task si ferma immediatamente, l'host viene segnato come fallito)

Tuttavia, questo semplice controllo spesso non cattura le sfumature degli script reali. Un comando potrebbe restituire un RC di 0 ma produrre comunque un risultato indesiderato (un fallimento logico), oppure un comando potrebbe restituire un RC non zero previsto (es. grep restituisce 1 se non trova corrispondenze).

Per gestire queste sfumature, dobbiamo catturare l'output e controllare condizionalmente lo stato di fallimento.

Passo 1: Catturare l'Output del Comando con register

Il primo passo per un debugging efficace è catturare tutti i flussi di output disponibili in una variabile Ansible usando la parola chiave register. Ciò consente di ispezionare il codice di ritorno, l'output standard e l'errore standard.

Per evitare che il playbook si fermi immediatamente in caso di codice di ritorno non zero durante i test iniziali, è spesso utile usare temporaneamente ignore_errors: yes.

- name: Esegui un comando potenzialmente inaffidabile e cattura i risultati
  ansible.builtin.shell: | 
    /usr/local/bin/check_config.sh 2>&1 || exit 1
  register: cmd_output
  ignore_errors: yes  # Permette temporaneamente a RC != 0 di procedere

Una volta registrata, la variabile cmd_output conterrà diverse chiavi utili, in particolare:

• cmd_output.rc: Il codice di ritorno intero.
• cmd_output.stdout: Il flusso di output standard.
• cmd_output.stderr: Il flusso di errore standard.
• cmd_output.failed: Un booleano che indica se Ansible considera attualmente il task fallito.

Passo 2: Ispezionare i Dati Catturati con debug

Usa il modulo debug immediatamente dopo il task fallito per ispezionare il contenuto della variabile registrata. Questo aiuta a distinguere tra un vero fallimento tecnico (es. comando non trovato) e un fallimento logico (es. lo script è stato eseguito ma ha riportato un errore interno).

- name: Mostra l'output completo catturato per il debugging
  ansible.builtin.debug:
    var: cmd_output
    # Usa 'when' per mostrarlo solo se il task è fallito, pulendo l'output
  when: cmd_output.failed is defined and cmd_output.failed

- name: Evidenzia il contenuto di stderr
  ansible.builtin.debug:
    msg: "STDERR catturato: {{ cmd_output.stderr }}"
  when: cmd_output.stderr | length > 0

Ispezionando l'output completo, puoi individuare il messaggio di errore specifico o il pattern che indica un vero fallimento.

Passo 3: Sovrascrivere il Comportamento di Fallimento Predefinito con failed_when

La condizione failed_when è lo strumento più potente per il debugging e la gestione dei risultati complessi dei moduli shell. Permette di definire una logica personalizzata, utilizzando espressioni Jinja2, per determinare se un task deve essere segnato come fallito, indipendentemente dal codice di ritorno predefinito.

Scenario A: Gestire un Codice di Ritorno Non Zero Previsto

Alcuni utility restituiscono un codice non zero per un risultato previsto. Ad esempio, grep restituisce 1 quando non trova corrispondenze e maggiore di 1 per errori reali.

- name: Verifica se un'impostazione esiste, ma non fallire se assente
  ansible.builtin.command: grep -q '^feature_enabled=true' /etc/myapp.conf
  register: grep_result
  failed_when: grep_result.rc > 1
  changed_when: false

Scenario B: Fallire su Errori Logici (RC=0, ma Output Errato)

Se uno script restituisce sempre RC=0 anche quando si verifica un errore interno, ma stampa una stringa di errore specifica su stdout o stderr, usa failed_when per catturare quella stringa.

- name: Valida lo script di connettività al database
  ansible.builtin.shell: /opt/scripts/db_connect_test.sh
  register: db_result
  # Controlla sia stdout che stderr per frasi di errore comuni
  failed_when: >
    ('Connection refused' in db_result.stderr) or
    ('Authentication failure' in db_result.stdout)

Scenario C: Combinare Controlli di RC e Output

Per controlli robusti, combina il codice di ritorno e i controlli del contenuto usando operatori logici (and, or, parentesi).

- name: Controlla i log di deployment
  ansible.builtin.shell: tail -n 50 /var/log/deployment.log
  register: log_check
  # Fallisce se RC è non zero OPPURE se l'output di successo contiene la parola 'FATAL'
  failed_when: log_check.rc != 0 or 'FATAL' in log_check.stdout

Suggerimento: Quando si usa failed_when, generalmente si dovrebbe rimuovere ignore_errors: yes a meno che non si voglia esplicitamente che il fallimento venga registrato ma il playbook continui.

Buone Pratiche per un'Esecuzione Affidabile dei Comandi

Per minimizzare la necessità di debugging complesso, segui questi standard quando scrivi task che usano command o shell:

1. Usa Sempre Percorsi Assoluti

Non fare affidamento sul $PATH dell'utente remoto. Specifica sempre il percorso completo dell'eseguibile (es. /usr/bin/python, non solo python). Questo evita fallimenti causati da ambienti inconsistenti o differenze sottili nel percorso di esecuzione.

2. Sfrutta le Condizioni Anziché la Logica Shell

Invece di usare logiche shell complesse come || o && all'interno del modulo shell, utilizza le condizioni native di Ansible (when:, failed_when:, changed_when:) e la parola chiave register. Questo mantiene la logica del playbook trasparente e più facile da debuggare.

3. Controlla Esplicitamente il Rilevamento delle Modifiche (changed_when)

Per impostazione predefinita, command e shell segnano un task come changed se il codice di ritorno è 0. Se il tuo script viene eseguito ma non apporta modifiche al sistema (es. un semplice controllo di stato), dovresti definire manualmente quando il task comporta una modifica usando changed_when.

- name: Controlla lo spazio su disco (non dovrebbe risultare in 'changed')
  ansible.builtin.command: df -h /data
  changed_when: false

4. Usa Moduli di Stato Dove Possibile

Se ti ritrovi a usare shell per verificare l'esistenza di un file, avviare/fermare servizi o installare pacchetti, fermati e cerca un modulo Ansible dedicato (es. ansible.builtin.stat, ansible.builtin.service, ansible.builtin.package). I moduli dedicati gestiscono internamente idempotenza e controllo degli errori, riducendo significativamente lo sforzo di debugging.

Conclusione Finale

Quando un task shell o command fallisce, cattura prima il risultato, ispeziona rc, stdout e stderr, quindi codifica la condizione di successo reale in failed_when. Una volta che il task è stabile, aggiungi changed_when in modo che i controlli di stato non mostrino false modifiche in ogni esecuzione del playbook.