Aller au contenu
Installer

volant shadow

Rejouer un run qu'ansible-playbook a enregistré, sans contacter d'hôte, et voir ce que Volant aurait fait autrement.

volant shadow replay lit un enregistrement du callback volant.compat.record (voir Enregistrements de runs). Il exécute les mêmes playbooks avec les mêmes options dans Volant et répond à chaque tâche qui atteindrait un hôte avec le résultat enregistré par ansible-core. Puis il compare ce que Volant a décidé avec ce qu’ansible-core a fait. Aucun hôte n’est contacté et aucun agent ne démarre. Changer sans risque parcourt tout le chemin, CI comprise.

Fenêtre de terminal
volant shadow replay RECORDING [--json] [--ledger PATH]
volant shadow status [--json] [--require-ready] [--ledger PATH]

Écrire le rapport en JSON Lines : un objet par divergence, puis un objet de résumé.

Le registre où ajouter ou lire, au lieu de .volant/shadow.jsonl à côté de l’ansible.cfg en vigueur (dans le répertoire de travail s’il n’y en a pas).

Sortir avec 1 sauf si chaque playbook du registre est ready.

L’enregistrement nomme les fichiers que le run a lus. Chacun est cherché depuis le répertoire de travail de l’enregistrement : lancez donc le rejeu au même endroit de votre dépôt. Le rejeu refuse de démarrer, avec le code de sortie 4, quand :

  • le format de l’enregistrement est plus récent que ce que lit cette version de Volant ; le message nomme les deux versions ;
  • un playbook ou un fichier d’inventaire diffère de celui enregistré (site.yml changed since the recording) ;
  • un fichier nommé par un argument -e @fichier a changé.

Un enregistrement d’un ansible-core hors de la série 2.19 est rejoué avec un avertissement out-of-profile. Un enregistrement coupé par un run tué est rejoué jusqu’à sa dernière ligne complète, et les hôtes s’arrêtent là où il s’arrête.

Les options du run viennent de l’enregistrement : inventaire, variables extra, tags, limite, modes check et diff, élévation de privilèges, identifiants de vault et forks. Vous ne les redonnez pas.

Les tâches qui atteignent un hôte reçoivent le résultat enregistré à la place. Volant applique ensuite lui-même changed_when, failed_when, register, les boucles et until. Un until reçoit dans l’ordre les tentatives échouées enregistrées. Un pause prend la réponse que son prompt a reçue et n’attend pas. Un hôte enregistré comme injoignable est injoignable. Les tâches exécutées sur le contrôleur, comme debug, set_fact, les includes et meta, sont calculées par Volant comme d’habitude.

Un playbook avec des modules Python ou une collecte de facts a toujours besoin d’ansible-core sur le contrôleur pour les préparer, par VOLANT_PYTHON ou le runtime géré.

Certaines valeurs diffèrent à chaque run : les lookups pipe, env, password, lines et url, tout lookup dont le nom contient random, un lookup file hors du répertoire où tourne le rejeu, now(), et les filtres random et shuffle. Pendant un rejeu, ils donnent à la place une valeur inconnue. C’est aussi le cas de toute clé lue dans un résultat no_log enregistré, puisque l’enregistrement n’en garde que le statut.

Une expression qui lit une valeur inconnue est inconnue tout entière, quoi qu’elle en fasse : du texte autour, un filtre, une comparaison, un attribut ou un élément. Un argument de tâche inconnu n’est pas comparé, et le rapport le compte sous unknown: suivi de la raison, par exemple unknown: lookup 'pipe'. Un when, un loop, un changed_when, un failed_when ou un until qui lit une valeur inconnue suit l’enregistrement : la tâche s’exécute ou est sautée comme elle l’a été, boucle sur les éléments enregistrés, garde le statut enregistré, et s’arrête à la tentative où l’enregistrement s’est arrêté.

Le run rejoué s’affiche sur stderr, exactement comme volant playbook le ferait. Le rapport va sur stdout. Il commence par un résumé : combien de tâches ont été comparées, sur combien d’hôtes, et les divergences par sorte. Il liste ensuite ce qui n’a pas été comparé et pourquoi, puis chaque divergence avec son hôte, son fichier:ligne, le nom de sa tâche, ce qu’ansible-core a fait, ce que Volant a fait et la différence :

Shadow replay: 23 tasks compared on 2 hosts, 1 divergence: judgment 1.
Arguments not compared: no_log 2, not in the recording 8.
judgment local site.yml:30 fails
ansible: {"status":"ok"}
volant: {"status":"failed"}
diff: status: "ok" -> "failed"

Une divergence est de l’une des cinq sortes suivantes, de la plus grave à la moins grave :

Sorte Ce qu’elle détecte
inventory Un hôte manque, ou appartient à d’autres groupes que dans l’enregistrement.
flow Une tâche qu’un moteur a exécutée et l’autre non, un ordre différent, ou un handler exécuté d’un seul côté.
loop Un nombre d’éléments différent, ou une valeur d’élément différente.
args Un argument que Volant envoie à un module avec une autre valeur que celle avec laquelle le module a tourné. Les arguments présents seulement dans l’enregistrement sont les valeurs par défaut du module et ne sont pas comparés.
judgment Un statut différent (ok, changed, failed, skipped), une autre condition qui a sauté la tâche, un nombre de tentatives différent, ou un récapitulatif différent.

Après la première divergence flow sur un hôte, la suite de cet hôte n’est pas comparée, car toutes les tâches suivantes sont décalées. Les autres hôtes restent comparés. Une tâche no_log est comparée sur son seul statut, puisque l’enregistrement n’en garde rien d’autre.

Avec --json, chaque divergence tient sur une ligne :

{"host":"local","task":{"path":"site.yml:30","name":"fails"},"kind":"judgment","ansible":{"status":"ok"},"volant":{"status":"failed"},"diff":"status: \"ok\" -> \"failed\""}

La dernière ligne est le résumé :

{"summary":{"compared":23,"hosts":2,"divergences":{"judgment":1},"not_compared":{"no_log":2},"arguments_not_compared":{"no_log":2,"not_recorded":8},"truncated":false}}

Les raisons de not_compared sont after_flow (après une divergence flow sur cet hôte), no_log (comparée sur le seul statut) et unknown: <raison> (un élément de boucle inconnu). Les raisons de arguments_not_compared sont no_log, not_recorded (ansible-core n’a passé aucun invocation au callback, comme pour debug, ou comme ansible-core 2.21 le fait pour toutes les tâches) controller (Volant a exécuté la tâche sur le contrôleur et n’a rien envoyé) et unknown: <raison>, compté par argument.

Un seul rejeu propre prouve peu de chose. Chaque rejeu qui n’est pas refusé ajoute une ligne au registre, .volant/shadow.jsonl à côté de l’ansible.cfg en vigueur : la date, les playbooks et leurs empreintes, la version de Volant, l’ansible-core et l’empreinte de l’enregistrement, l’empreinte de volant.lock s’il existe, le --limit et les --tags du run, le nombre d’hôtes, les tâches comparées et non comparées, le fichier:ligne de chaque tâche comparée et de chaque tâche compilée par le rejeu, les divergences par sorte, et clean, dirty ou out-of-profile. Volant ne décide pas où vit le registre entre deux runs : versionnez-le, ou gardez-le dans le cache de votre CI.

volant shadow status le lit et donne une ligne par playbook :

  • La série est le nombre de rejeux clean d’affilée. Un rejeu dirty la remet à zéro, comme une nouvelle version de Volant. Un playbook ou une collection modifiés ne la remettent pas à zéro, car les deux moteurs exécutent les mêmes fichiers. Les rejeux out-of-profile ne comptent ni dans un sens ni dans l’autre.
  • La couverture est la part des tâches du playbook, toutes branches comprises, que les rejeux de la série ont comparées au moins une fois. Les tâches jamais comparées sont listées par nom.
  • Le verdict est ready quand la série atteint shadow_runs (5 par défaut) et la couverture shadow_coverage (0.9 par défaut), tous deux lus dans la section [volant] de l’ansible.cfg. Il est diverged quand le dernier rejeu était dirty, et not-ready sinon, avec la raison.
site.yml not-ready streak 2/5, coverage 96% of 25 tasks (1 never compared), no divergence
2 clean replays in a row, 5 wanted

Avec --json, chaque ligne est un objet avec playbook, verdict, streak, coverage, tasks, never_compared, last_divergence et reasons. Une ligne du registre illisible est ignorée, avec un avertissement qui donne son numéro.

Code Signification
0 Aucune divergence.
1 Au moins une divergence.
4 L’enregistrement ne peut pas être rejoué sur ce dépôt : un format plus récent, ou un fichier qui a changé.

volant shadow status sort avec 0, ou avec 1 sous --require-ready quand un playbook n’est pas ready ou que le registre est vide.