Caradoc un outil de tracing Ansible

Mis à jour le 22 mai 2025 Publié le 19 août 2024

5 min de lecture

Je vous propose de découvrir caradoc, un callback Ansible qui peut vous aider à déboguer vos playbooks. Il n'est pas sans rappeler ARA, qui permet de stocker les traces de vos exécutions dans une base de données sqlite locale, voir sur un serveur distant.

Introduction

Je suis sûr que comme moi, vous galérez quand il s'agit de comprendre ce qui plante dans une exécution de playbooks. On n'a jamais assez de traces et celles rendues par le mode debug est difficile à lire. C'est là qu'intervient caradoc, un plugin écrit par Joël Seguillon.

Caradoc permet de créer des traces lisibles dans un répertoire local. Ces traces sont écrites en asciidoc, qui peut être rendu directement dans votre éditeur de code favori. Par exemple moi, j'ai installé l'extension VsCode AsciiDoctor

Installation de caradoc

Tout est documenté dans le dépôt du projet :

mkdir -p ~/.ansible/plugins/callback
cd ~/.ansible/plugins/callback
curl -SL -O https://raw.githubusercontent.com/jseguillon/caradoc/main/plugins/callback/caradoc.py

À partir de là, vous pouvez ajouter le callback à votre configuration ansible (par exemple depuis là où se trouve vos playbooks) :

vi ansible.cfg

[defaults]
callbacks_enabled = caradoc

Lecture des traces produites

Si vous lancez l'exécution d'un playbook, vous devriez trouver dans votre répertoire un dossier .caradoc. Contenant les traces d'exécution.

├───📁 20221207-164446/
│   ├───📁 plays/
│   │   └───...
│   ├───📄 README.adoc
│   └───📄 charts.adoc
├───📄 .caradoc.css.adoc
└───📄 .caradoc.env.adoc

Une fois l'extension Vscode installée, de cliquer sur le fichier README.adoc d'une exécution et de sélectioner [Open Preview].

caradoc ansible

Le rendu est vraiment explicite.

Il suffit de naviguer dans les taches via les liens pour trouver toutes les traces de celles-ci.

caradoc ansible

Plus loin avec caradoc

J'imagine déjà l'utiliser dans mes pipelines de CI-CD, d'ailleurs, il suffit de s'inspirer de cette Github actions fournie par l'auteur :

      - name: Build html doc via asciidoctor
        id: adocbuild
        uses: tonynv/asciidoctor-action@755dc03a42aee715c3705fc31d2ca106b7ee90fd  # v2
        with:
          program: |
            cd .caradoc/*
            asciidoctor '**/*.adoc' -r asciidoctor-kroki  -a kroki-server-url=https://kroki.io -a source-file-scheme=https:// -a last-update-label="Ansible report by <a href='https://github.com/jseguillon/caradoc'>Caradoc</a> - "
      - name: Add index.html redirect, rewrite src path and add favico
        run: |
          target_dir="$(ls -d .caradoc/*/)"
          cp ${GITHUB_WORKSPACE}/docs/favicon.ico $target_dir
          taget_dir_relpath="$(basename $target_dir)"
          cat <<EOF > .caradoc/index.html
            <html>
                    <head>
                    <meta http-equiv="refresh" content="0; url=${taget_dir_relpath}/README.html" />a
                    </head>
            </html>
          EOF
          find .caradoc/ -type f -exec sed -i  's#\(/home/runner/work/caradoc/caradoc/\)\([^:]*\):\([^:]*\)#github.com/jseguillon/caradoc/blob/main/\2\#L\3#g'  {} \;

Si vous avez des suggestions, créer simplement une issue sur le dépôt du projet. On remercie Joël car ce callback va vous faire gagner du temps.