Choose the ansible-core release per project, and keep what Ansible removes
Decision record 0010.
| Status | Date |
|---|---|
| accepted | 2026-10-25 |
Context
Section titled “Context”Volant reproduces ansible-core 2.19.12 (decision 0002). Ansible keeps moving: 2.20 and 2.21 are out and 2.22 is in release candidate. Each release removes or changes behaviour that playbooks rely on. Some teams stay on the release they run today, others want the newest behaviour, and a single reference cannot serve both.
On 2026-10-25 the golden corpus was recorded again under ansible-core 2.20.10, 2.21.5 and 2.22.0rc1 and compared with the 2.19.12 recordings, after removing times, job ids and process ids. The corpus covers templates, inventories and 355 scenarios run 1032 times. Fourteen files differ under 2.20, 76 under 2.21 and 94 under 2.22. Most changes are small, such as a key added to a result or a new prefix on an error, but some change a run: a loop result no longer has skipped, so a playbook that reads r.skipped stops with exit code 2 under 2.21. The appendix lists them.
Decision
Section titled “Decision”Profiles
Section titled “Profiles”A profile is the ansible-core release whose behaviour Volant reproduces. Two exist: 2.19, which is the default and stays what Volant does today, and 2.22, added once ansible-core 2.22.0 is out and its corpus is recorded. latest names the newest profile Volant carries.
From 2.22 on, a profile is added for each ansible-core release, in the Volant release that ships its recordings, and latest moves to it. A profile is dropped when ansible-core ends support for its release. The releases between 2.19 and 2.22 get no profile of their own: their changes are part of 2.22.
A project picks a profile with [volant] core_version in its ansible.cfg or the VOLANT_CORE_VERSION environment variable, which wins over the file. The value is a release (2.19, 2.22) or latest. Any other value stops the run with exit code 5 and lists the profiles. How volant.lock records the profile is decided with the lock itself, in #653.
ansible_version reports the profile’s release: 2.19.12 under 2.19, and the patch release the 2.22 corpus was recorded with under 2.22. This extends decision 0003. volant_version does not change.
Python modules come from the ansible-core installed on the controller (decision 0006), so their results follow that release whatever the profile. Volant warns at the start of a run when the installed release differs from the profile.
Switches by behaviour
Section titled “Switches by behaviour”There is one engine. Each difference between releases is a named switch with the release it starts in, such as loop-results-omit-skipped from 2.21, and the code asks the profile whether the switch is on. Each switch has an entry of the same name in the registry below.
Separate behaviour sets were set aside: the measured differences are small and spread across the engine, so a copy per release would duplicate almost everything to change a key here and a message there.
Module and action-plugin code is never forked. A native module or an action plugin has one implementation, and a difference between releases is a switch inside it. A switch is tested by a scenario recorded under each release it changes, and the golden test runs every scenario under each profile against that profile’s recording.
The corpus per profile
Section titled “The corpus per profile”just golden takes the release as an argument and records with an ansible-core of that release, installed in a uv environment of its own. The recordings of 2.19 stay where they are. Another profile writes expected.<release>.json next to expected.json, only for the scenarios whose result differs: 94 of 355 under 2.22.
The controller’s Python is pinned with the release. The measurement found that it changes results too: with the same 2.19 templates, Python 3.12 and 3.13 answer differently to 'abcabc'.replace('b', 'X', count=1), to wrong arguments to string methods and to sorting a list that holds nan.
Recording takes about 52 minutes per release for the template, inventory and scenario goldens on a 4-core machine. It is done once by a maintainer, as today, and CI never records. CI compares Volant with the committed recordings, which costs one more run of the golden tests per profile.
A behaviour enters a profile only with a recording from that release.
The registry
Section titled “The registry”The registry lists what Ansible removed or changed, in crates/volant/src/profile/registry.toml. Each entry has a name (the switch), the feature, the release it was removed or changed in (removed_in), its kind (security or compat), the replacement, the warning and, for a known upstream bug, which behaviour Volant follows (follow, release or 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"Under a profile at or after removed_in, a compat feature keeps working, with the warning followed by “Volant still runs it” and the replacement. A security feature stays off unless [volant] allow_insecure_legacy = true. Under an older profile the feature is simply there, without a warning.
An entry is security when the release notes tie the change to a CVE, when the removed behaviour can show a secret, or when it lets playbook content read or write outside what it was given. A security fix that ansible-core ships in a 2.19 patch release after 2.19.12 also applies to the 2.19 profile. The known security entries are:
debugshowing a registered secret, andno_logoptions replaced by a placeholder in results, both changed in 2.22;- secret masking with
$REDACTED$in all output and inlog_path, 2.22; tempfileaccepting a path inprefixandsuffix, removed in 2.19.13, 2.20.9 and 2.21.4;- credentials shown in URLs by
uri,get_url,apt_key,rpm_keyand theurllookup, masked from 2.19.13, 2.20.9 and 2.21.4; - the ansible-connection persistent directory without private permissions, fixed in 2.19.14, 2.20.10 and 2.21.5;
ansible-galaxy collection installacceptingFILES.jsonentries outside the collection (CVE-2026-89091), 2.22.0rc1.
The other removals of the porting guides are compat: among them DEFAULT_TRANSPORT=smart and the vaultid parameter of the vault filters (2.20), the paramiko connection plugin and the gpg_whitelist alias of git (2.21), and yes and no for follow_redirects (2.22).
volant upgrade-plan
Section titled “volant upgrade-plan”volant upgrade-plan [PATH...] [--to PROFILE] [--json]It reads the playbooks, roles, inventories and ansible.cfg under PATH (the current directory by default) and lists each use of a feature that the target profile (latest by default) removes or changes compared with the profile in effect. Each finding gives the file:line, the registry entry and the suggested change.
Some changes cannot be found by reading, such as a result read through a computed name or the text of an error. The report ends with the registry entries between the two profiles that it cannot check. For those, a project records a run under its current release and replays it under the target profile with volant shadow replay. The divergences are the changes the run would meet.
The exit codes are 0 when nothing was found, 1 when at least one use was found, 4 when a file cannot be read and 5 for an unknown profile. --json gives one object per finding: path, line, name, removed_in, kind and suggestion.
Known regressions
Section titled “Known regressions”Volant follows the release when a change is deliberate. It follows the documented behaviour when the release’s behaviour is an open bug upstream that runs the wrong thing on a host. The answer is per case and goes in the registry’s follow field. For the regressions known in 2.21:
- interpreter discovery reusing another host’s interpreter path (ansible/ansible#87288):
documented, each host gets its own discovery; - the discovery warning naming the inventory host instead of the delegated one (ansible/ansible#87298):
documented; - discovery not cached for delegated hosts (ansible/ansible#86517):
documented, since only the time differs; dnffailing when a dnf plugin prints to stdout (ansible/ansible#87366):release. The module runs from the controller’s ansible-core and Volant does not patch modules. No change to the output of a successfuldnfwas found in the changelog or the issue tracker.
The lock
Section titled “The lock”volant.lock pins the engine that runs a project. Whether it records the profile, and what a run does when the lock and core_version disagree, is decided in #653.
Consequences
Section titled “Consequences”- A project that sets nothing keeps the
2.19behaviour. - A project that moves to
latestkeeps its removed features, with a warning, except the security ones. - Every difference costs a switch, a registry entry and a recording before it ships in a profile.
- The implementation follows in these issues, by size:
- the profile setting,
VOLANT_CORE_VERSION,ansible_versionper profile and the check of the controller’s ansible-core (medium); - recording per profile: the release argument of
just golden,expected.<release>.jsonand the golden tests per profile (medium); - the registry, its warnings and
allow_insecure_legacy(medium); - the switches of the
2.22profile, from the appendix below (large, split by area once the setting lands); volant upgrade-plan(medium).
- the profile setting,
Appendix: corpus diff, 2026-10-25
Section titled “Appendix: corpus diff, 2026-10-25”ansible-core 2.20.10, 2.21.5 and 2.22.0rc1 against 2.19.12. The first three ran on Python 3.12, 2.22.0rc1 on Python 3.13. Left out: host order under order: shuffle and under throttle, which varies from run to run; job file paths and process ids; ansible_version itself; and the template differences that came from Python rather than from ansible-core.
| Feature | 2.19.12 | 2.20 | 2.21 | 2.22 | Kind |
|---|---|---|---|---|---|
regex test with an unknown match_type |
'str' object is not callable |
Invalid match_type specified |
as 2.20 | as 2.20 | template |
password_hash with a given salt |
uses the salt ($1$saltsalt$…) |
as 2.19 | another salt ($1$n34PoBLM$…) |
as 2.21 | template |
Error inside a when |
Error while evaluating conditional: … |
as 2.19 | A 'when' expression failed: … |
as 2.21 | template |
A failing command’s msg |
non-zero return code |
as 2.19 | The command exited with a non-zero return code. |
as 2.21 | module |
include_vars errors |
path unquoted | path quoted | as 2.20 | as 2.20 | module |
Check-mode result of copy |
no file key |
file key |
as 2.20 | as 2.20 | module |
command whose chdir fails |
rc: null |
as 2.19 | no rc key |
as 2.21 | module |
cmd of a command not found |
a string | as 2.19 | as 2.19 | a list | module |
ansible_parsed in module results |
absent | absent | absent | true |
module |
skipped: false in loop results |
present | present | absent | absent | scenario |
changed_when_result |
absent | absent | present | present | scenario |
failed_when message |
Action failed: Unknown error. or the action’s name |
as 2.19 | A 'failed_when' expression evaluated to 'True'. |
as 2.21 | scenario |
until retry line and attempts |
(1 retries left), attempts: 1 |
as 2.19 | (0 retries left), attempts: 2 |
as 2.21 | scenario |
| Loop items reading a fact set in the same loop | a-1, b-2, c-3 |
as 2.19 | a-0, b-1, c-2 |
as 2.21 | scenario |
any_errors_fatal: "{{ false }}" after a failure |
the other host stops | as 2.19 | the other host goes on | as 2.21 | scenario |
Missing file in include_tasks |
include and reason keys |
as 2.19 | msg and an [ERROR] line |
as 2.21 | scenario |
Missing copy source |
one-line message | as 2.19 | <<< caused by >>> and the paths searched |
as 2.21 | scenario |
| Role file outside the role | exit code 4 | exit code 4 | exit code 1 | exit code 1 | scenario |
debug of an undefined msg |
{"msg": null} |
as 2.19 | {} |
as 2.21 | scenario |
--start-at-task with a role argument spec |
validation skipped | validation runs | as 2.20 | as 2.20 | scenario |
ansible --help |
-K alone |
-K | --become-password-file |
as 2.20 | as 2.20 | scenario |
| Secret values in output | shown | shown | shown | $REDACTED$, even inside a path |
scenario |
Vaulted value in ansible-inventory --graph |
shown | shown | shown | $REDACTED$ |
inventory |
Under 2.22 the masking also hid parts of output that are not secrets: the become password wrong turned the directory become-su-local-wrong-password into become-su-local-$REDACTED$-password.