Zum Inhalt springen
Installieren

volant shadow

Einen Lauf, den ansible-playbook aufgezeichnet hat, ohne Kontakt zu einem Host wiederholen und sehen, was Volant anders gemacht hätte.

volant shadow replay liest eine Aufzeichnung des Callbacks volant.compat.record (siehe Aufzeichnungen von Läufen). Es führt dieselben Playbooks mit denselben Optionen in Volant aus und beantwortet jeden Task, der einen Host erreichen würde, mit dem Ergebnis, das ansible-core aufgezeichnet hat. Dann vergleicht es, was Volant entschieden hat, mit dem, was ansible-core getan hat. Kein Host wird kontaktiert und kein Agent gestartet. Ohne Risiko umsteigen geht den ganzen Weg durch, CI eingeschlossen.

Terminal-Fenster
volant shadow replay RECORDING [--json] [--ledger PATH]
volant shadow status [--json] [--require-ready] [--ledger PATH]

Den Bericht als JSON Lines schreiben: ein Objekt pro Abweichung, dann ein Zusammenfassungsobjekt.

Das Register, an das angehängt oder aus dem gelesen wird, statt .volant/shadow.jsonl neben der geltenden ansible.cfg (im Arbeitsverzeichnis, wenn es keine gibt).

Mit 1 beenden, außer jedes Playbook im Register ist ready.

Die Aufzeichnung nennt die Dateien, die der Lauf gelesen hat. Jede wird vom Arbeitsverzeichnis der Aufzeichnung aus gesucht, starten Sie die Wiederholung also an derselben Stelle Ihres Repositorys. Die Wiederholung startet nicht und endet mit Exit-Code 4, wenn:

  • das Format der Aufzeichnung neuer ist, als diese Volant-Version liest; die Meldung nennt beide Versionen;
  • ein Playbook oder eine Inventardatei von der aufgezeichneten abweicht (site.yml changed since the recording);
  • sich eine Datei geändert hat, die ein -e @datei-Argument nennt.

Eine Aufzeichnung einer ansible-core-Version außerhalb der Reihe 2.19 wird mit einer out-of-profile-Warnung wiederholt. Eine Aufzeichnung, die ein abgebrochener Lauf unvollständig hinterlassen hat, wird bis zu ihrer letzten vollständigen Zeile wiederholt, und die Hosts halten dort an, wo sie endet.

Die Optionen des Laufs stammen aus der Aufzeichnung: Inventar, Extra-Variablen, Tags, Limit, Check- und Diff-Modus, Rechteausweitung, Vault-IDs und Forks. Sie geben sie nicht erneut an.

Tasks, die einen Host erreichen, erhalten stattdessen das aufgezeichnete Ergebnis. Volant wendet danach changed_when, failed_when, register, Schleifen und until selbst an. Ein until erhält die aufgezeichneten fehlgeschlagenen Versuche der Reihe nach. Ein pause übernimmt die Antwort, die sein Prompt bekommen hat, und wartet nicht. Ein als unerreichbar aufgezeichneter Host ist unerreichbar. Tasks, die auf dem Controller laufen, etwa debug, set_fact, Includes und meta, berechnet Volant wie gewohnt.

Ein Playbook mit Python-Modulen oder Fact-Erfassung braucht weiterhin ansible-core auf dem Controller, um sie vorzubereiten, über VOLANT_PYTHON oder die verwaltete Laufzeit.

Manche Werte sind bei jedem Lauf anders: die Lookups pipe, env, password, lines und url, jeder Lookup mit random im Namen, ein file-Lookup außerhalb des Verzeichnisses, in dem die Wiederholung läuft, now() sowie die Filter random und shuffle. In einer Wiederholung liefern sie stattdessen einen unbekannten Wert. Ebenso jeder Schlüssel, der aus einem aufgezeichneten no_log-Ergebnis gelesen wird, da die Aufzeichnung nur dessen Status behält.

Ein Ausdruck, der einen unbekannten Wert liest, ist als Ganzes unbekannt, egal was er damit macht: Text darum herum, ein Filter, ein Vergleich, ein Attribut oder ein Element. Ein unbekanntes Task-Argument wird nicht verglichen, und der Bericht zählt es unter unknown: mit dem Grund, etwa unknown: lookup 'pipe'. Ein when, ein loop, ein changed_when, ein failed_when oder ein until, das einen unbekannten Wert liest, folgt der Aufzeichnung: Der Task läuft oder wird übersprungen wie damals, durchläuft die aufgezeichneten Elemente, behält den aufgezeichneten Status und hält bei dem Versuch an, bei dem die Aufzeichnung anhielt.

Der wiederholte Lauf erscheint auf stderr, genau wie bei volant playbook. Der Bericht geht auf stdout. Er beginnt mit einer Zusammenfassung: wie viele Tasks auf wie vielen Hosts verglichen wurden und die Abweichungen nach Art. Danach listet er, was nicht verglichen wurde und warum, und jede Abweichung mit Host, Datei:Zeile, Task-Name, dem, was ansible-core getan hat, dem, was Volant getan hat, und dem Unterschied:

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"

Eine Abweichung gehört zu einer von fünf Arten, von der schwersten an:

Art Was sie erkennt
inventory Ein Host fehlt oder gehört zu anderen Gruppen als in der Aufzeichnung.
flow Ein Task, den eine Engine ausgeführt hat und die andere nicht, eine andere Reihenfolge oder ein Handler, der nur auf einer Seite lief.
loop Eine andere Anzahl von Elementen oder ein anderer Elementwert.
args Ein Argument, das Volant mit einem anderen Wert an ein Modul sendet als dem, mit dem das Modul lief. Argumente, die nur in der Aufzeichnung stehen, sind Standardwerte des Moduls und werden nicht verglichen.
judgment Ein anderer Status (ok, changed, failed, skipped), eine andere Bedingung, die den Task übersprungen hat, eine andere Anzahl von Versuchen oder eine andere Zusammenfassung.

Nach der ersten flow-Abweichung auf einem Host wird der Rest dieses Hosts nicht verglichen, weil jeder folgende Task verschoben ist. Die anderen Hosts werden weiter verglichen. Ein no_log-Task wird nur nach seinem Status verglichen, da die Aufzeichnung nichts anderes von ihm behält.

Mit --json steht jede Abweichung in einer Zeile:

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

Die letzte Zeile ist die Zusammenfassung:

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

Die Gründe in not_compared sind after_flow (nach einer flow-Abweichung auf diesem Host), no_log (nur nach dem Status verglichen) und unknown: <Grund> (ein unbekanntes Schleifenelement). Die Gründe in arguments_not_compared sind no_log, not_recorded (ansible-core hat dem Callback kein invocation übergeben, wie bei debug oder wie ansible-core 2.21 bei jedem Task) controller (Volant hat den Task auf dem Controller ausgeführt und nichts gesendet) und unknown: <Grund>, pro Argument gezählt.

Eine einzelne saubere Wiederholung beweist wenig. Jede Wiederholung, die nicht abgelehnt wird, hängt eine Zeile an das Register .volant/shadow.jsonl neben der geltenden ansible.cfg an: das Datum, die Playbooks und ihre Hashes, die Volant-Version, ansible-core und Hash der Aufzeichnung, den Hash von volant.lock, falls vorhanden, --limit und --tags des Laufs, die Anzahl der Hosts, die verglichenen und nicht verglichenen Tasks, Datei:Zeile jedes verglichenen und jedes von der Wiederholung kompilierten Tasks, die Abweichungen nach Art und clean, dirty oder out-of-profile. Volant entscheidet nicht, wo das Register zwischen den Läufen liegt: Versionieren Sie es oder halten Sie es im CI-Cache.

volant shadow status liest es und gibt eine Zeile pro Playbook aus:

  • Die Serie ist die Anzahl der clean-Wiederholungen in Folge. Eine dirty-Wiederholung setzt sie zurück, ebenso eine neue Volant-Version. Ein geändertes Playbook oder eine geänderte Collection setzt sie nicht zurück, weil beide Engines dieselben Dateien ausführen. out-of-profile-Wiederholungen zählen in keine Richtung.
  • Die Abdeckung ist der Anteil der Tasks des Playbooks, alle Zweige eingeschlossen, den die Wiederholungen der Serie mindestens einmal verglichen haben. Nie verglichene Tasks werden mit Namen aufgeführt.
  • Das Urteil ist ready, wenn die Serie shadow_runs (standardmäßig 5) und die Abdeckung shadow_coverage (standardmäßig 0.9) erreicht, beide aus dem Abschnitt [volant] der ansible.cfg gelesen. Es ist diverged, wenn die letzte Wiederholung dirty war, und sonst not-ready, mit Begründung.
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

Mit --json ist jede Zeile ein Objekt mit playbook, verdict, streak, coverage, tasks, never_compared, last_divergence und reasons. Eine unlesbare Registerzeile wird mit einer Warnung, die ihre Zeilennummer nennt, ausgelassen.

Code Bedeutung
0 Keine Abweichung.
1 Mindestens eine Abweichung.
4 Die Aufzeichnung lässt sich in diesem Repository nicht wiederholen: ein neueres Format oder eine geänderte Datei.

volant shadow status endet mit 0, oder unter --require-ready mit 1, wenn ein Playbook nicht ready oder das Register leer ist.