Elegir la versión de ansible-core por proyecto y conservar lo que Ansible retira
Registro de decisión 0010.
| Estado | Fecha |
|---|---|
| aceptada | 2026-10-25 |
Contexto
Sección titulada «Contexto»Volant reproduce ansible-core 2.19.12 (decisión 0002). Ansible sigue avanzando: 2.20 y 2.21 ya salieron y 2.22 está en release candidate. Cada versión retira o cambia comportamientos de los que dependen los playbooks. Algunos equipos se quedan en la versión que usan hoy, otros quieren el comportamiento más reciente, y una sola referencia no puede servir a los dos.
El 2026-10-25 se volvió a grabar el corpus golden con ansible-core 2.20.10, 2.21.5 y 2.22.0rc1, y se comparó con las grabaciones de 2.19.12 tras quitar las horas, los identificadores de job y los identificadores de proceso. El corpus cubre templates, inventarios y 355 escenarios ejecutados 1032 veces. Catorce archivos difieren con 2.20, 76 con 2.21 y 94 con 2.22. La mayoría de los cambios son pequeños, como una clave añadida a un resultado o un prefijo nuevo en un error, pero algunos cambian una ejecución: un resultado de bucle ya no tiene skipped, así que un playbook que lee r.skipped se detiene con el código de salida 2 en 2.21. El anexo los enumera.
Decisión
Sección titulada «Decisión»Los perfiles
Sección titulada «Los perfiles»Un perfil es la versión de ansible-core cuyo comportamiento reproduce Volant. Hay dos: 2.19, el predeterminado, que sigue siendo lo que Volant hace hoy, y 2.22, que se añade cuando salga ansible-core 2.22.0 y se grabe su corpus. latest designa el perfil más reciente que trae Volant.
A partir de 2.22 se añade un perfil por cada versión de ansible-core, en la versión de Volant que publica sus grabaciones, y latest pasa a ese perfil. Un perfil se retira cuando ansible-core deja de mantener su versión. Las versiones entre 2.19 y 2.22 no tienen perfil propio: sus cambios forman parte de 2.22.
Un proyecto elige su perfil con [volant] core_version en su ansible.cfg o con la variable de entorno VOLANT_CORE_VERSION, que tiene prioridad sobre el archivo. El valor es una versión (2.19, 2.22) o latest. Cualquier otro valor detiene la ejecución con el código de salida 5 y enumera los perfiles. Cómo registra volant.lock el perfil se decide junto con el propio lock, en #653.
ansible_version indica la versión del perfil: 2.19.12 con 2.19, y con 2.22 la versión de parche con la que se grabó el corpus de 2.22. Esto amplía la decisión 0003. volant_version no cambia.
Los módulos Python vienen del ansible-core instalado en el controlador (decisión 0006), así que sus resultados siguen esa versión sea cual sea el perfil. Volant avisa al empezar una ejecución cuando la versión instalada no coincide con el perfil.
Interruptores por comportamiento
Sección titulada «Interruptores por comportamiento»Hay un solo motor. Cada diferencia entre versiones es un interruptor con nombre y con la versión en la que empieza, por ejemplo loop-results-omit-skipped desde 2.21, y el código pregunta al perfil si el interruptor está activo. Cada interruptor tiene una entrada con el mismo nombre en el registro de abajo.
Se descartaron los conjuntos de comportamiento separados: las diferencias medidas son pequeñas y están repartidas por el motor, así que una copia por versión duplicaría casi todo para cambiar una clave aquí y un mensaje allá.
El código de los módulos y de los action plugins nunca se bifurca. Un módulo nativo o un action plugin tiene una sola implementación, y una diferencia entre versiones es un interruptor dentro de ella. Un interruptor se prueba con un escenario grabado en cada versión que cambia, y la prueba golden ejecuta cada escenario con cada perfil contra la grabación de ese perfil.
El corpus por perfil
Sección titulada «El corpus por perfil»just golden recibe la versión como argumento y graba con un ansible-core de esa versión, instalado en un entorno uv propio. Las grabaciones de 2.19 se quedan donde están. Otro perfil escribe expected.<versión>.json junto a expected.json, solo para los escenarios cuyo resultado difiere: 94 de 355 con 2.22.
El Python del controlador se fija junto con la versión. La medición mostró que también cambia los resultados: con los mismos templates de 2.19, Python 3.12 y 3.13 responden distinto a 'abcabc'.replace('b', 'X', count=1), a argumentos erróneos en métodos de cadena y a ordenar una lista que contiene nan.
Grabar lleva unos 52 minutos por versión para los goldens de templates, inventarios y escenarios en una máquina de 4 núcleos. Lo hace una vez un mantenedor, como hoy, y la CI nunca graba. La CI compara Volant con las grabaciones del repositorio, lo que cuesta una ejecución más de las pruebas golden por perfil.
Un comportamiento entra en un perfil solo con una grabación de esa versión.
El registro
Sección titulada «El registro»El registro enumera lo que Ansible retiró o cambió, en crates/volant/src/profile/registry.toml. Cada entrada tiene un name (el interruptor), la funcionalidad (feature), la versión en que se retiró o cambió (removed_in), su tipo (kind, security o compat), el reemplazo (replacement), el aviso (warning) y, para un bug conocido aguas arriba, el comportamiento que sigue Volant (follow, release o documented).
[[change]]name = "debug-shows-registered-secret"feature = "showing a registered secret with `debug`"removed_in = "2.22"kind = "security"replacement = "write the value to a file with `copy` and `no_log: true`"warning = "showing a registered secret with debug was removed in ansible-core 2.22"
[[change]]name = "interpreter-auto-legacy"feature = "`interpreter_python = auto_legacy` and `auto_legacy_silent`"removed_in = "2.21"kind = "compat"replacement = "`auto` or `auto_silent`"warning = "interpreter_python = auto_legacy was removed in ansible-core 2.21"
[[change]]name = "loop-results-omit-skipped"feature = "`skipped: false` in each loop result"removed_in = "2.21"kind = "compat"replacement = "`r.skipped | default(false)`"warning = "loop results lost their skipped key in ansible-core 2.21"Con un perfil igual o posterior a removed_in, una funcionalidad compat sigue funcionando, con el aviso seguido de «Volant still runs it» y del reemplazo. Una funcionalidad security queda desactivada salvo con [volant] allow_insecure_legacy = true. Con un perfil anterior, la funcionalidad simplemente está, sin aviso.
Una entrada es security cuando las notas de la versión relacionan el cambio con una CVE, cuando el comportamiento retirado puede mostrar un secreto, o cuando permite al contenido de un playbook leer o escribir fuera de lo que se le dio. Una corrección de seguridad que ansible-core publica en una versión de parche de 2.19 posterior a 2.19.12 también se aplica al perfil 2.19. Las entradas security conocidas son:
debugmostrando un secreto registrado, y las opcionesno_logsustituidas por un texto de reemplazo en los resultados, ambos cambiados en 2.22;- el enmascarado de secretos con
$REDACTED$en toda la salida y enlog_path, 2.22; tempfileaceptando una ruta enprefixysuffix, retirado en 2.19.13, 2.20.9 y 2.21.4;- las credenciales mostradas en las URL por
uri,get_url,apt_key,rpm_keyy el lookupurl, enmascaradas desde 2.19.13, 2.20.9 y 2.21.4; - el directorio persistente de ansible-connection sin permisos privados, corregido en 2.19.14, 2.20.10 y 2.21.5;
ansible-galaxy collection installaceptando entradas deFILES.jsonfuera de la colección (CVE-2026-89091), 2.22.0rc1.
Las demás retiradas de las guías de migración son compat: entre ellas DEFAULT_TRANSPORT=smart y el parámetro vaultid de los filtros vault (2.20), el connection plugin paramiko y el alias gpg_whitelist de git (2.21), y yes y no para follow_redirects (2.22).
volant upgrade-plan
Sección titulada «volant upgrade-plan»volant upgrade-plan [PATH...] [--to PROFILE] [--json]El comando lee los playbooks, roles, inventarios y el ansible.cfg bajo PATH (el directorio actual por defecto) y enumera cada uso de una funcionalidad que el perfil de destino (latest por defecto) retira o cambia respecto al perfil vigente. Cada hallazgo indica el archivo:línea, la entrada del registro y el cambio sugerido.
Algunos cambios no se encuentran leyendo, como un resultado leído mediante un nombre calculado o el texto de un error. El informe termina con las entradas del registro entre los dos perfiles que no puede comprobar. Para esas, un proyecto graba una ejecución con su versión actual y la reproduce con el perfil de destino mediante volant shadow replay. Las divergencias son los cambios que encontraría la ejecución.
Los códigos de salida son 0 cuando no se encontró nada, 1 cuando se encontró al menos un uso, 4 cuando no se puede leer un archivo y 5 para un perfil desconocido. --json da un objeto por hallazgo: path, line, name, removed_in, kind y suggestion.
Regresiones conocidas
Sección titulada «Regresiones conocidas»Volant sigue la versión cuando un cambio es intencionado. Sigue el comportamiento documentado cuando el de la versión es un bug abierto aguas arriba que ejecuta lo que no debe en un host. La respuesta se decide caso por caso y va en el campo follow del registro. Para las regresiones conocidas de 2.21:
- el descubrimiento de intérprete que reutiliza la ruta de intérprete de otro host (ansible/ansible#87288):
documented, cada host tiene su propio descubrimiento; - el aviso de descubrimiento que nombra el host del inventario en lugar del host delegado (ansible/ansible#87298):
documented; - el descubrimiento sin caché para los hosts delegados (ansible/ansible#86517):
documented, ya que solo cambia el tiempo; dnffallando cuando un plugin de dnf escribe en stdout (ansible/ansible#87366):release. El módulo se ejecuta desde el ansible-core del controlador y Volant no parchea módulos. No se encontró ningún cambio en la salida de undnfcorrecto ni en el changelog ni en el gestor de issues.
El lock
Sección titulada «El lock»volant.lock fija el motor que ejecuta un proyecto. Si registra el perfil, y qué hace una ejecución cuando el lock y core_version no coinciden, se decide en #653.
Consecuencias
Sección titulada «Consecuencias»- Un proyecto que no configura nada conserva el comportamiento de
2.19. - Un proyecto que pasa a
latestconserva sus funcionalidades retiradas, con un aviso, salvo las de seguridad. - Cada diferencia cuesta un interruptor, una entrada en el registro y una grabación antes de entrar en un perfil.
- La implementación sigue en estas issues, por tamaño:
- el ajuste del perfil,
VOLANT_CORE_VERSION,ansible_versionpor perfil y la comprobación del ansible-core del controlador (mediana); - la grabación por perfil: el argumento de versión de
just golden,expected.<versión>.jsony las pruebas golden por perfil (mediana); - el registro, sus avisos y
allow_insecure_legacy(mediana); - los interruptores del perfil
2.22, según el anexo de abajo (grande, dividida por áreas cuando el ajuste esté listo); volant upgrade-plan(mediana).
- el ajuste del perfil,
Anexo: diff del corpus, 2026-10-25
Sección titulada «Anexo: diff del corpus, 2026-10-25»ansible-core 2.20.10, 2.21.5 y 2.22.0rc1 frente a 2.19.12. Las tres primeras se ejecutaron con Python 3.12, 2.22.0rc1 con Python 3.13. Quedan fuera: el orden de los hosts con order: shuffle y con throttle, que varía de una ejecución a otra; las rutas de los archivos de job y los identificadores de proceso; el propio ansible_version; y las diferencias de templates que venían de Python y no de ansible-core.
| Funcionalidad | 2.19.12 | 2.20 | 2.21 | 2.22 | Tipo |
|---|---|---|---|---|---|
Test regex con un match_type desconocido |
'str' object is not callable |
Invalid match_type specified |
como 2.20 | como 2.20 | template |
password_hash con una sal dada |
usa la sal ($1$saltsalt$…) |
como 2.19 | otra sal ($1$n34PoBLM$…) |
como 2.21 | template |
Error dentro de un when |
Error while evaluating conditional: … |
como 2.19 | A 'when' expression failed: … |
como 2.21 | template |
msg de un comando que falla |
non-zero return code |
como 2.19 | The command exited with a non-zero return code. |
como 2.21 | módulo |
Errores de include_vars |
ruta sin comillas | ruta entre comillas | como 2.20 | como 2.20 | módulo |
Resultado de copy en check mode |
sin clave file |
clave file |
como 2.20 | como 2.20 | módulo |
command cuyo chdir falla |
rc: null |
como 2.19 | sin clave rc |
como 2.21 | módulo |
cmd de un comando no encontrado |
una cadena | como 2.19 | como 2.19 | una lista | módulo |
ansible_parsed en los resultados de módulo |
ausente | ausente | ausente | true |
módulo |
skipped: false en los resultados de bucle |
presente | presente | ausente | ausente | escenario |
changed_when_result |
ausente | ausente | presente | presente | escenario |
Mensaje de failed_when |
Action failed: Unknown error. o el nombre de la acción |
como 2.19 | A 'failed_when' expression evaluated to 'True'. |
como 2.21 | escenario |
Línea de reintento de until y attempts |
(1 retries left), attempts: 1 |
como 2.19 | (0 retries left), attempts: 2 |
como 2.21 | escenario |
| Elementos de bucle que leen un fact fijado en el mismo bucle | a-1, b-2, c-3 |
como 2.19 | a-0, b-1, c-2 |
como 2.21 | escenario |
any_errors_fatal: "{{ false }}" tras un fallo |
el otro host se detiene | como 2.19 | el otro host sigue | como 2.21 | escenario |
Archivo que falta en include_tasks |
claves include y reason |
como 2.19 | msg y una línea [ERROR] |
como 2.21 | escenario |
Origen de copy que falta |
mensaje de una línea | como 2.19 | <<< caused by >>> y las rutas buscadas |
como 2.21 | escenario |
| Archivo de rol fuera del rol | código de salida 4 | código de salida 4 | código de salida 1 | código de salida 1 | escenario |
debug de un msg no definido |
{"msg": null} |
como 2.19 | {} |
como 2.21 | escenario |
--start-at-task con una especificación de argumentos de rol |
validación omitida | validación ejecutada | como 2.20 | como 2.20 | escenario |
ansible --help |
solo -K |
-K | --become-password-file |
como 2.20 | como 2.20 | escenario |
| Valores secretos en la salida | mostrados | mostrados | mostrados | $REDACTED$, incluso dentro de una ruta |
escenario |
Valor cifrado con vault en ansible-inventory --graph |
mostrado | mostrado | mostrado | $REDACTED$ |
inventario |
Con 2.22 el enmascarado también ocultó partes de la salida que no son secretos: la contraseña de become wrong convirtió el directorio become-su-local-wrong-password en become-su-local-$REDACTED$-password.