Déboguer vos playbooks Ansible

Introduction

Lors du dépannage des problèmes Ansible, il est utile de savoir comment tester votre playbook en toute sécurité, activer le mode de débogage et augmenter le niveau de verbosité. Nous allons apprendre à faire tout cela dans ce chapitre.

Les différentes manières de débogage

Mode vérification

Des fois, vous aurez besoin de vérifier si une tâche est fonctionnelle sur vos serveurs distants sans avoir à effectuer de modifications sur vos systèmes distants. Pour ce cas d'utilisation, il faut penser à l'option --check de la commande ansible-playbook.

ansible-playbook main.yml --check

Parfois, vous souhaiterez peut-être enter en mode de vérification sur des tâches individuelles. Cela peut se faire via l'instruction check_mode, qui peut être ajoutée à vos tâches, comme suit :

tasks:
  - name: Add test text in /home/hatim/hatim.txt
    lineinfile:
        line: "test"
        dest: /home/hatim/hatim.txt
        state: present
    check_mode: yes

Si vous souhaitez utiliser l'option --check et ignorer les erreurs sur certaines tâches en mode vérification, vous pouvez utiliser la variable booléenne ansible_check_mode qui aura comme valeur True pendant le mode vérification :

tasks:
  - name: Add test text in /home/hatim/notfound.txt
    lineinfile:
        line: "test"
        dest: /home/hatim/notfound.txt
        state: present
    ignore_errors: '{{ ansible_check_mode }}'
    # Vous pouvez aussi l'instruction suivante: when: not ansible_check_mode
  
  - debug: msg="Si vous voyez ce message c'est que la tâche précédente a été ignorée"

Exécutons le playbook pour voir le résultat :

ansible-playbook main.yml --check

Résultat :

TASK [Add test text in /home/hatim/notfound.txt] ************
fatal: [localhost]: FAILED! => {"changed": false, "msg": "Destination /home/hatim/notfound.txt does not exist !", "rc": 257}
...ignoring

TASK [debug] *******************
ok: [localhost] => {
    "msg": "Si vous voyez ce message c'est que la tâche précédente a été ignorée"
}

Mode différenciation

C'est bien beau tout ça, mais ça serait mieux si Ansible nous avertit des modifications qu'il est supposé apporter sur la machine cible. Pour cela il existe l'option --diff qui est principalement utilisée dans les modules qui manipulent des fichiers, mais d'autres modules peuvent également afficher des informations «avant et après» (par exemple, le module user). D'ailleurs, elle fonctionne très bien avec l'option --check :

Reprenons l'exécution de notre exemple précédent :

tasks:
  - name: Add test text in /home/hatim/hatim.txt
    lineinfile:
        line: "test"
        dest: /home/hatim/hatim.txt
        state: present

ansible-playbook main.yml --check --diff

Résultat :

TASK [Add test text in /home/hatim/hatim.txt] *********************************************
--- before: /home/hatim/hatim.txt (content)
+++ after: /home/hatim/hatim.txt (content)
@@ -0,0 +1 @@
+test

changed: [localhost]

Si vous souhaitez activer la différence sur une tâche particulière, vous pouvez utiliser l'instruction booléenne diff. Selon comment vous lancez votre playbook, vous pouvez déclencher les comportements suivants :

• Si vous n'êtes pas en mode différenciation et que l'instruction diff est à True alors seule la tâche exécutant cette instruction entrera en mode différenciation.
• Si êtes en mode différenciation et que l'instruction diff est à False alors seule la tâche exécutant cette instruction ignorera le mode différenciation.

Voici comment elle s'intègre dans un playbook :

tasks:
  - name: Add test text in /home/hatim/hatim.txt
    lineinfile:
        line: "test"
        dest: /home/hatim/hatim.txt
        state: present
    diff: no

Le debugger des playbooks

Ansible inclut un débogueur, ce débogueur vous permet de déboguer vos tâches, c'est-à-dire que vous avez accès à toutes les fonctionnalités du débogueur dans le contexte de la tâche. Vous pouvez par exemple, vérifier ou modifier la valeur des variables de votre playbook, mettre à jour les arguments de votre module/tâche et relancer votre tâche avec les nouvelles variables et les nouveaux arguments pour vous aider à résoudre la cause de l'échec.

Pour utiliser le débogueur d'Ansible vous devez utiliser l'instruction debugger qui peut prendre les valeurs suivantes :

• always: appeler toujours le débogueur, quel que soit le résultat.
• never: n'invoquer jamais le débogueur, quel que soit le résultat.
• on_failed: n'appeler le débogueur qu'en cas d'échec d'une tâche.
• on_unreachable: n'appeler le débogueur que si l'hôte a est inaccessible.
• on_skipped: n'appeler le débogueur uniquement si la tâche est ignorée.

L'instruction debugger peut être utilisée sur une tâche particulière ou pour toutes vos tâches.

Pour une tâche particulière :

- name: Execute a command
  command: ls -l /home/hatim
  debugger: on_failed

Pour toutes vos tâches :

- hosts: all
  debugger: on_failed
  tasks:
    - name: Execute a command
      command: ls -l /home/hatim

Quand vous entrez en mode debug vous pouvez utiliser différentes commandes :

• p task/task_vars/host/result: affiche des informations utilisées pendant l'exécution par votre tâche module(le p équivaut au print).
• task.args[key] = value: met à jour l'argument du module.
• task_vars[key] = value: met à jour les variables de votre playbook.
• update_task: si vous modifiez les task_vars alors utilisez cette commande pour recréer la tâche à partir de votre nouvelle structure de données.
• redo: exécutez à nouveau la tâche.
• continue: passe à la tâche suivante.
• quit: quitte le débogueur. L'exécution du playbook est abandonnée.

Voici ci-dessous un exemple d'utilisation, je vais intentionnellement utiliser le module lineinfile avec un fichier qui n'existe pas, et par la suite je vais déboguer cette tâche pour remettre le bon chemin de mon fichier. Voici déjà à quoi ressemble mon playbook avec notre mauvaise valorisation :

tasks:
  - name: Add test text in /home/hatim/hatim.txt
    lineinfile:
        line: "test"
        dest: /home/hatim/hatim_fault.txt
        state: present
    debugger: on_failed

En exécutant notre playbook, nous nous retrouverons en mode debug :

ansible-playbook main.yml

Résultat :

TASK [Add test text in /home/hatim/hatim.txt] **************
fatal: [localhost]: FAILED! => {"changed": false, "msg": "Destination /home/hatim/hatim_fault.txt does not exist !", "rc": 257}
[localhost] TASK: Add test text in /home/hatim/hatim.txt (debug)>

Nous savons par avance que l'erreur vient de la mauvaise valorisation du paramètre dest, nous allons donc modifier sa valeur dans notre débogueur. Voici la démarche que je vais suivre pour arriver à notre but :

• Afficher plus d'informations sur notre erreur.
• Afficher les valeurs des différents arguments de notre tâche.
• Modifier la valeur de notre paramètre dest.
• Afficher la nouvelle valeur de notre paramètre dest.
• Exécuter de nouveau notre tâche.

Si nous transformons notre démarche sous forme de commandes dans notre outil de débogage, nous taperons les commandes suivantes :

(debug)> p result._result
{'_ansible_no_log': False,
 '_ansible_parsed': True,
 'changed': False,
 u'failed': True,
 u'invocation': {u'module_args': {u'attributes': None,
                                  ...
                                  u'delimiter': None,
                                  u'dest': u'/home/hatim/hatim_fault.txt',
                                  u'directory_mode': None,
                                  ...
 u'msg': u'Destination /home/hatim/hatim_fault.txt does not exist !',
 u'rc': 257}

(debug)> p task.args
{'_ansible_check_mode': False,
 ...
 u'dest': u'/home/hatim/hatim_fault.txt',
 u'line': u'test',
 u'state': u'present'}

(debug)> task.args['dest'] = '/home/hatim/hatim.txt'

(debug)> p task.args['dest']
'/home/hatim/hatim.txt'

(debug)> redo
changed: [localhost]

PLAY RECAP ****************************************************************************
localhost : ok=1    changed=1    unreachable=0    failed=0

Enfin vous pouvez activer le mode débogage pour chaque exécution de votre playbook en mettant la variable enable_task_debugger à True dans le fichier ansible.cfg:

[defaults]
enable_task_debugger = True

La verbosité dans Ansible

Pour comprendre ce qui se passe lorsque vous exécutez le playbook, vous pouvez exécuter la commande ansible-playbook avec l' option verbose -v. Chaque "v" supplémentaire fournira à l'utilisateur final plus de sortie de débogage (vous pouvez aller jusqu'à 4 niveaux de verbosité) :

# verbosité niveau 0
ansible-playbook main.yml

# verbosité niveau 1
ansible-playbook -v main.yml

# verbosité niveau 2
ansible-playbook -vv main.yml

# verbosité niveau 3
ansible-playbook -vvv main.yml

# verbosité niveau 4
ansible-playbook -vvvv main.yml

Vous pouvez également modifier la fichier ansible.cfg pour appliquer un niveau de verbosité pour chaque exécution de vos playbooks :

[defaults]
verbosity  = 3

Conclusion

Nous avons étudié de nombreuses manières de procéder à des tests sécurisés de vos playbooks , et vous avez désormais tous les outils à votre disposition pour identifier et corriger vos bogues à partir de votre playbook. Rendez-vous au prochain chapitre où nous aborderons la notion de performance pour nos playbooks.