Will my playbook run?
Check an existing Ansible project against this release in a few seconds, without touching a host.
To find out whether a playbook runs, run volant check . at the root of the repository, then run the playbook on one host. Volant reads the whole ansible-core 2.19 grammar, so your playbook parses here as it parses under Ansible. Before it connects to anything, a second check, the pre-flight check, looks for what this release does not support yet and stops the run with a message that names it. The known gaps below are the exceptions: a run can ignore a setting or give a wrong result there without an error.
Check a project
Section titled “Check a project”-
Check every playbook at once, without contacting a host:
Terminal window volant check .Each playbook gets a verdict:
ready,refusedwith the reason, file and line, orunknownwhen only a run can tell.volant playbook --checkis a different command: it runs the playbook in check mode against hosts. Seevolant check. -
Read it without running it. Listings and
--syntax-checknever stop on an unsupported module or keyword, so they work even on a playbook this release cannot run yet:Terminal window volant playbook -i inventory.ini site.yml --syntax-checkvolant playbook -i inventory.ini site.yml --list-tasksIf the task list matches what
ansible-playbook --list-tasksprints, Volant compiled your roles, imports and tags the same way. -
Ask for a real run against one host you can afford to touch.
--check --diffleaves the host as it is, except for the cached agent, so it is a safe first run:Terminal window volant playbook -i inventory.ini site.yml --limit test1 --check --diffvolant playbook -i inventory.ini site.yml --limit test1Most of what this release cannot execute stops the run before it connects. The message names the module, the keyword or the value, and the run exits with code 4. What it refuses today lists the messages.
-
Fix or wait. What is not supported yet is listed in Keywords, Modules and the known gaps below, and most have a workaround.
Questions people ask
Section titled “Questions people ask”| Question | Answer |
|---|---|
Does community.general work? |
Yes, once it is installed. Volant does not install a collection during a run, so run volant runtime install --collections community.general first. A plugin that needs a Python package the managed runtime does not carry, such as the json_query filter with jmespath, fails. Use your own Python with VOLANT_PYTHON for those. See The managed runtime. |
Does copy work? |
Yes. The controller reads the file, or takes content:, and sends it to the host. A directory as src works too. See Modules. |
Does async work? |
Yes: async, poll, and poll: 0 with async_status. A module that ansible-core cannot run under async fails on each host with This action (<name>) does not support async. See Running plays. |
Does --diff work? |
Yes, with --check or alone. A host needs Python for apt, user, group, file, lineinfile and systemd when a run asks for a check or a diff. See Check mode, diff and listings. |
Do become, vault and ansible.cfg work? |
become through sudo or su, vault and ansible.cfg work. doas and other methods do not. See Connections and become. |
| Do plugins of my own work? | Partly. Action, connection, inventory, callback, cache and vars plugins beside the playbook or in a role run through ansible-core. See the known gaps. |
At a glance
Section titled “At a glance”| Area | Runs today | Not yet |
|---|---|---|
| Plays | pre_tasks, roles, tasks, post_tasks, handlers, serial, strategy (linear, free, host_pinned, debug), order, throttle, timeout, debugger, any_errors_fatal, max_fail_percentage, ignore_errors, ignore_unreachable |
|
| Tasks | when, loop, every with_<lookup> form, register, until, retries, changed_when, failed_when, ignore_errors, ignore_unreachable, any_errors_fatal, no_log, environment, timeout, tags, async, poll, module_defaults |
|
| Blocks | block, rescue, always |
|
| Reuse | roles and dependencies, import_tasks, import_role, import_playbook, include_tasks, include_role, include_vars |
|
| Delegation | delegate_to, delegate_facts, local_action, run_once |
|
| Modules | the modules of ansible-core for Linux hosts, including copy, template, dnf, service, uri and reboot, and the modules of installed collections with their action plugins, and action plugins in an action_plugins/ beside the playbook or in a role |
a collection’s action plugin that needs Windows |
| Inventories | INI, YAML and TOML files, directories, scripts, constructed, generator and collection plugins, several -i, group_vars, host_vars, the jsonfile fact cache |
none left |
| Connections | ssh with keys, an ssh-agent or a password (-k or ansible_password, needs OpenSSH 8.4 or later), local, and network_cli, netconf and httpapi for network devices |
other connection plugins, Windows |
| Escalation | become through sudo or su, with or without a password |
doas and other methods |
| Templating | Jinja2 with the Ansible filters, tests and lookups, !unsafe, filters and lookups from collections |
some filter arguments, listed in Templating |
| Run modes | normal runs, --check and --diff, vault, --start-at-task, --step, the four listing commands |
none left |
Common blockers and what to do
Section titled “Common blockers and what to do”| Not supported yet | Why | What you can do today |
|---|---|---|
| A collection that is not installed | Volant does not install one during a run. It asks the controller’s ansible-core what is installed, before the first connection. | Run volant runtime install --collections NAME, the command the error names. See The managed runtime and Modules from collections. |
| No Python with ansible-core on the controller | Volant installs its own on first need, with curl or wget and tar. |
Nothing, or volant runtime install ahead of time. Without a network, use volant runtime pack and install --from. |
apt, user, group or file under --check or --diff on a host with no Python |
These modules answer through Python on the host when the run asks for a check or a diff. | Install Python on the host, or run the play without --check and --diff. |
!!binary, a duplicate anchor, or a date or a set as a typed value |
Volant has no type for bytes, dates or sets. A date loads as its ISO text, a !!set, !!omap or !!pairs as the mapping or list it is written as. !!binary stops the load, and a second &anchor of the same name is accepted. |
Write the value as a plain string, list or mapping, and give each anchor its own name. |
| Arithmetic on an integer wider than 128 bits | The operators +, -, *, /, //, % and ** and the abs and round filters refuse a wide operand. See Templating. |
Do the arithmetic in a module or in command with python3 -c, and keep the wide value as text. |
What it refuses today
Section titled “What it refuses today”The pre-flight check stops the run before the first connection, before any banner and before any recap. Without it, a keyword that slipped past would be ignored in silence, and the run would report success after skipping what you asked for. The pre-flight check describes how it works.
| What | Message shape | Exit code |
|---|---|---|
A strategy other than linear, free, host_pinned and debug, from the play or from ANSIBLE_STRATEGY, unless its plugin subclasses one of them and adds nothing |
ansible-core’s deprecation of strategy plugins outside ansible.builtin, then strategy 'x' is not supported yet |
4 |
until, retries or delay on include_tasks or include_role |
keyword 'until' is not supported yet on 'include_tasks' |
4 |
A pause with a prompt and seconds or minutes, when standard input is a terminal |
pause cannot wait for a prompt and a duration together on a terminal ... |
4 |
| A module argument that ansible-core has and this release does not act on | argument 'x' is not supported yet on 'module', with with 'v' when only that value is refused |
4 |
end_role outside a role |
Cannot execute 'end_role' from outside of a role |
4 |
| A built-in module this release does not carry | module 'x' is not available in this release |
4 |
A module or collection that does not resolve, written as the task’s key (one named in action: or local_action: fails the task when it runs, with Cannot resolve 'x' to an action or module.) |
couldn't resolve module/action 'x' ..., with the install command for a missing collection |
4 |
| A collection module that needs an action plugin for Windows | module 'x' needs an action plugin from its collection, which this release does not run |
4 |
A become_method other than sudo and su |
become_method 'x' is not supported yet |
2 |
A role in roles: or import_role that nobody can find |
the role 'x' was not found in ... |
1 |
The pause refusal applies only to a step that always runs. A when, a loop or a rescue around it leaves the check to the moment the pause is reached. A run the check stops exits with code 4, the code Ansible uses for a playbook it cannot load. Exit codes lists every code.
Known gaps
Section titled “Known gaps”These differ from ansible-playbook without a message before the run, or with a message that names something else. Each row says what happens.
| What | What happens |
|---|---|
A task with no_log: true that fails |
On purpose. Volant prints [ERROR]: Task failed: Action failed: <error censored due to no log> and nothing else of the cause. ansible-core 2.19.12 prints the cause: [ERROR]: Task failed: Action failed: <the msg of fail or assert>, the error of the module, and the <<< caused by >>> blocks. That text can hold a secret, such as the msg of a fail that names a password. The security policy counts a secret that reaches a log or a terminal where no_log hides it in ansible-core as a vulnerability, so Volant hides it. The fatal: line, the registered result and the recap are the same in both. To read the cause, run the task without no_log. |
| SIGTERM | On purpose. Volant stops cleanly: it cancels the running tasks, removes the directory that holds the connection password, prints the recap, and exits with code 99, as it does for Ctrl-C. ansible-playbook does not catch SIGTERM. It dies at once with code 143 and prints no recap. Measured with kill -TERM during a command: sleep: 99 under Volant, 143 under ansible-core 2.19.12. |
_ansible_ansiballz_pydevd_config |
On purpose. Ignored. ansible-core keeps this setting for its own use: it attaches a debugger to the module wrapper. Volant runs Python modules with its own runner, and its native modules without Python. |
Templating lists the filters and arguments that fail. The parity page marks a filter partial when one of its arguments fails.
If a playbook behaves differently under Volant and ansible-playbook without being reported as unsupported, that is a bug. Please open a compatibility report with a minimal playbook.
Look up a name
Section titled “Look up a name”When you need to know about one keyword, module, filter or option, open the reference page for it:
- Keywords lists every play, block, task and loop keyword and what Volant does with it.
- Modules lists the modules that run in the agent, on the controller and through Python, with the arguments each one supports.
- Command line lists every option of
volant playbookandvolant runtime. - Parity is the full matrix: each keyword, option and plugin of ansible-core 2.19.12, and each module, filter, test and lookup of the collections in the ansible 12.3.0 package, with a
runs,partial,not yetorlaterstatus.