volant shadow
Reproducir una ejecución que ansible-playbook grabó, sin contactar ningún host, y ver qué habría hecho Volant de otra manera.
volant shadow replay lee una grabación del callback volant.compat.record (ver Grabaciones de ejecuciones). Ejecuta los mismos playbooks con las mismas opciones en Volant y responde a cada tarea que llegaría a un host con el resultado que grabó ansible-core. Después compara lo que decidió Volant con lo que hizo ansible-core. No se contacta ningún host y no arranca ningún agente. Cambiar sin riesgo recorre todo el camino, CI incluida.
volant shadow replay RECORDING [--json] [--ledger PATH]volant shadow status [--json] [--require-ready] [--ledger PATH]Escribir el informe como JSON Lines: un objeto por divergencia y, al final, un objeto de resumen.
El registro donde añadir o leer, en lugar de .volant/shadow.jsonl junto al ansible.cfg en vigor (en el directorio de trabajo si no hay ninguno).
Salir con 1 salvo que cada playbook del registro esté ready.
Antes de la reproducción
Sección titulada «Antes de la reproducción»La grabación nombra los archivos que leyó la ejecución. Cada uno se busca desde el directorio de trabajo de la grabación, así que lanza la reproducción en el mismo lugar de tu repositorio. La reproducción se niega a empezar, con el código de salida 4, cuando:
- el formato de la grabación es más reciente del que lee esta versión de Volant; el mensaje nombra las dos versiones;
- un playbook o un archivo de inventario difiere del grabado (
site.yml changed since the recording); - ha cambiado un archivo que nombra un argumento
-e @archivo.
Una grabación de un ansible-core fuera de la serie 2.19 se reproduce con un aviso out-of-profile. Una grabación cortada por una ejecución interrumpida se reproduce hasta su última línea completa, y los hosts se detienen donde ella termina.
Qué ejecuta la reproducción
Sección titulada «Qué ejecuta la reproducción»Las opciones de la ejecución salen de la grabación: inventario, variables extra, tags, límite, modos check y diff, escalada de privilegios, identificadores de vault y forks. No hace falta volver a darlas.
Las tareas que llegan a un host reciben en su lugar el resultado grabado. Después Volant aplica por sí mismo changed_when, failed_when, register, los bucles y until. Un until recibe en orden los intentos fallidos grabados. Un pause toma la respuesta que recibió su prompt y no espera. Un host grabado como inalcanzable es inalcanzable. Las tareas que se ejecutan en el controlador, como debug, set_fact, los includes y meta, las calcula Volant como de costumbre.
Un playbook con módulos Python o recogida de facts sigue necesitando ansible-core en el controlador para prepararlos, mediante VOLANT_PYTHON o el runtime gestionado.
Los valores que cambian de una ejecución a otra
Sección titulada «Los valores que cambian de una ejecución a otra»Algunos valores son distintos en cada ejecución: los lookups pipe, env, password, lines y url, cualquier lookup con random en su nombre, un lookup file fuera del directorio donde se ejecuta la reproducción, now(), y los filtros random y shuffle. En una reproducción dan en su lugar un valor desconocido. Lo mismo ocurre con cualquier clave leída de un resultado no_log grabado, ya que la grabación solo guarda su estado.
Una expresión que lee un valor desconocido es desconocida por completo, haga lo que haga con él: texto alrededor, un filtro, una comparación, un atributo o un elemento. Un argumento de tarea desconocido no se compara, y el informe lo cuenta bajo unknown: seguido del motivo, por ejemplo unknown: lookup 'pipe'. Un when, un loop, un changed_when, un failed_when o un until que lee un valor desconocido sigue la grabación: la tarea se ejecuta o se salta como entonces, recorre los elementos grabados, conserva el estado grabado y se detiene en el intento en que se detuvo la grabación.
El informe
Sección titulada «El informe»La ejecución reproducida se muestra en stderr, exactamente como lo haría volant playbook. El informe va a stdout. Empieza con un resumen: cuántas tareas se compararon, en cuántos hosts, y las divergencias por tipo. Después lista lo que no se comparó y por qué, y cada divergencia con su host, su archivo:línea, el nombre de su tarea, lo que hizo ansible-core, lo que hizo Volant y la diferencia:
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"Una divergencia es de uno de estos cinco tipos, del más grave al menos grave:
| Tipo | Qué detecta |
|---|---|
inventory |
Falta un host, o pertenece a grupos distintos de los de la grabación. |
flow |
Una tarea que un motor ejecutó y el otro no, un orden distinto, o un handler que solo se ejecutó en un lado. |
loop |
Un número de elementos distinto, o un valor de elemento distinto. |
args |
Un argumento que Volant envía a un módulo con un valor distinto del que usó el módulo. Los argumentos que solo están en la grabación son los valores por defecto del módulo y no se comparan. |
judgment |
Un estado distinto (ok, changed, failed, skipped), otra condición que saltó la tarea, un número de intentos distinto, o un resumen final distinto. |
Tras la primera divergencia flow en un host, el resto de ese host no se compara, porque todas las tareas siguientes quedan desplazadas. Los demás hosts se siguen comparando. Una tarea no_log se compara solo por su estado, ya que la grabación no guarda nada más de ella.
Con --json, cada divergencia ocupa una línea:
{"host":"local","task":{"path":"site.yml:30","name":"fails"},"kind":"judgment","ansible":{"status":"ok"},"volant":{"status":"failed"},"diff":"status: \"ok\" -> \"failed\""}La última línea es el resumen:
{"summary":{"compared":23,"hosts":2,"divergences":{"judgment":1},"not_compared":{"no_log":2},"arguments_not_compared":{"no_log":2,"not_recorded":8},"truncated":false}}Los motivos de not_compared son after_flow (tras una divergencia flow en ese host), no_log (comparada solo por el estado) y unknown: <motivo> (un elemento de bucle desconocido). Los motivos de arguments_not_compared son no_log, not_recorded (ansible-core no pasó ningún invocation al callback, como ocurre con debug, o como hace ansible-core 2.21 con todas las tareas) controller (Volant ejecutó la tarea en el controlador y no envió nada) y unknown: <motivo>, contado por argumento.
El registro y el veredicto
Sección titulada «El registro y el veredicto»Una sola reproducción limpia prueba poco. Cada reproducción que no se rechaza añade una línea al registro, .volant/shadow.jsonl junto al ansible.cfg en vigor: la fecha, los playbooks y sus hashes, la versión de Volant, el ansible-core y el hash de la grabación, el hash de volant.lock si existe, el --limit y los --tags de la ejecución, el número de hosts, las tareas comparadas y no comparadas, el archivo:línea de cada tarea comparada y de cada tarea que compiló la reproducción, las divergencias por tipo, y clean, dirty o out-of-profile. Volant no decide dónde vive el registro entre ejecuciones: versiónalo o guárdalo en la caché de tu CI.
volant shadow status lo lee y da una fila por playbook:
- La racha es el número de reproducciones
cleanseguidas. Una reproduccióndirtyla reinicia, igual que una nueva versión de Volant. Un playbook o una colección modificados no la reinician, porque los dos motores ejecutan los mismos archivos. Las reproduccionesout-of-profileno cuentan en ningún sentido. - La cobertura es la parte de las tareas del playbook, con todas sus ramas, que las reproducciones de la racha compararon al menos una vez. Las tareas nunca comparadas se listan por nombre.
- El veredicto es
readycuando la racha llega ashadow_runs(5 por defecto) y la cobertura ashadow_coverage(0.9 por defecto), ambos leídos de la sección[volant]delansible.cfg. Esdivergedcuando la última reproducción fuedirty, ynot-readyen otro caso, con el motivo.
site.yml not-ready streak 2/5, coverage 96% of 25 tasks (1 never compared), no divergence 2 clean replays in a row, 5 wantedCon --json, cada fila es un objeto con playbook, verdict, streak, coverage, tasks, never_compared, last_divergence y reasons. Una línea del registro que no se puede leer se omite con un aviso que da su número de línea.
Códigos de salida
Sección titulada «Códigos de salida»| Código | Significado |
|---|---|
| 0 | Ninguna divergencia. |
| 1 | Al menos una divergencia. |
| 4 | La grabación no se puede reproducir en este repositorio: un formato más reciente, o un archivo que cambió. |
volant shadow status sale con 0, o con 1 bajo --require-ready cuando un playbook no está ready o el registro está vacío.