Ansible - Caradoc peut vous rendre la vie plus facile
Publié le : 7 décembre 2022 | Mis à jour le : 22 janvier 2023
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.
Table des matières
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].
Le rendu est vraiment explicite.
Il suffit de naviguer dans les taches via les liens pour trouver toutes les traces de celles-ci.
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@master
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.