Delegation, meta tasks and environment
Running a task once for a batch or on another host, what each meta action does, and how environment and no_log shape a task.
This page answers how to run a task somewhere other than where the play is working, how to steer the run itself with meta, and how to set environment variables or hide output for a task.
run_once
Section titled “run_once”run_once runs a task on one host of the batch and gives every other host what it produced, including anything it registered.
- name: Run database migrations once command: /opt/app/migrate.sh run_once: trueThe hosts of the batch meet in front of such a task before any of them runs it. The election has to be the same for everyone, and the other hosts have to wait for the one that runs.
run_once can be a template. Each host of the batch renders it in turn, and the first host for which it is true runs the task. A template that answers differently across the batch ends the run with exit 4.
Under strategy: free and host_pinned, run_once is ignored with a warning and the task runs for every host. A run_once task that fails there fails only its own host. See Other strategies.
delegate_to
Section titled “delegate_to”delegate_to runs a task somewhere other than the host it is running for.
- name: Take the host out of the load balancer command: /usr/local/bin/lb-drain {{ inventory_hostname }} delegate_to: lb1The task travels over the delegate’s own connection, with the delegate’s connection settings. The result still belongs to the host the play is working on: the recap counts that host, and the result line reads [web1 -> lb1].
- A task skipped by
whennever reached the delegate, so itsskipping:line has no arrow. - The delegating host’s own connection is not opened for a delegated task, so a task delegated away from an unreachable host still runs.
- The delegate is looked up in the whole inventory, not only the play’s hosts. A play over two hosts can delegate to a third that stays out of the recap.
- A name the inventory does not have is treated as an SSH target of that name, and reported unreachable if that fails. An unreachable delegate takes the delegating host out of the run.
delegate_facts: true stores what the task produced on the delegate instead of on the hosts that ran it.
A controller-side module such as set_fact or debug always runs on the controller, whatever delegate_to says. The delegate then only decides the name shown on the result line and, with delegate_facts, whose facts are written.
action: and local_action: take a string (command echo hi), a mapping with module: that Ansible deprecates, or a bare module name with the arguments under args:. The module may be a template, such as action: "{{ module_to_run }} msg=hi": it is rendered for each host when the task runs, and the banner shows it as written. The modules are built before the first connection, so a run with such a template builds every builtin Python module and every module in a library/ directory the run searches. A template that names a module of a collection, and no task names that module outright, fails the task. A word such as module=command after action: names no module. The task fails when a host reaches it, with exit 2, and a rescue or ignore_errors takes the failure, as in Ansible.
delegate_to and delegate_facts can be written on a block and on a task, not on a play, which is where Ansible accepts them too. The two keywords combine: a run_once task with a delegate_to runs once, on the delegate.
Meta tasks
Section titled “Meta tasks”meta asks the engine for something instead of running a module. Every action Ansible 2.19 has runs here, and each one prints a TASK [meta] banner. An action Ansible does not have prints the banner, then fails with invalid meta action requested: <action> and an Origin block, with exit 1, even when its when is false. A meta task adds nothing to the recap: its skipping: line is not counted either.
| Action | What it does | Whose when counts |
|---|---|---|
flush_handlers |
Runs the handlers the host has been told about, where the task stands. | Each host’s own. |
noop |
Nothing. | Ignored, with a warning. |
end_host |
The host leaves the play. No more tasks, no always sections, no handlers. |
Each host’s own. |
end_role |
The host skips the rest of the role it is in, an always section of the role included. |
Each host’s own. |
end_batch |
The batch ends for every host, and the next batch starts. | The first host’s. |
end_play |
The play ends for every host, with whatever batches are left. | The first host’s. |
clear_facts |
Forgets the facts modules gathered, on every host of the batch. Facts from set_fact stay. |
The first host’s. |
clear_host_errors |
Forgives the failures and the unreachable hosts of the batch. See below. | The first host’s. |
refresh_inventory |
Reads every inventory source again. See below. | Ignored, with a warning. |
reset_connection |
Closes the host’s connection, and the shared ssh connection with it. The next task opens both again. |
Ignored, with a warning. |
“The first host” is the first host of the batch that is still in the play, in inventory order. The actions that read its when run once and print one banner. The others run for each host and print one banner per host that is still in the play.
end_role outside a role stops the run before it starts, with exit 4 and ansible-core’s message.
Hosts that leave
Section titled “Hosts that leave”A host that ends with end_host, end_batch or end_play has not failed, and the recap shows it as it stood. Inside a rescue, the failure it rescued counts as rescued and the host stays out of the exit code. A host that had already failed keeps its failure. Later plays run on the host again.
Forgiving errors
Section titled “Forgiving errors”clear_host_errors takes the failures of the batch off the exit code. The recap keeps its counts, so a host can show failed=1 in a run that exits 0.
- A host that failed does not come back to the play it failed in. It is back in the plays after it. The exception is the host that runs the
clear_host_errorsitself, in thealwaysof a block whoserescuefailed: it stays in the play and runs the tasks after the block. - A host that went unreachable comes back. It picks the play up where it stopped, and runs the steps it missed after every other host is done. If it is unreachable again, it counts again.
- A host that was unreachable in an earlier play also comes back, from the first task of the play that cleared. It is unreachable again in the plays after, and the exit code says 4 either way.
Refreshing the inventory
Section titled “Refreshing the inventory”refresh_inventory reads every inventory source again, in the order of -i. groups and hostvars change at once. A host the sources gained joins from the next play, and a host they lost leaves the play where it stands, without failing. --limit is resolved again too, so a host it names that only the new sources hold joins as well. Hosts and groups made by add_host and group_by stay. If the sources cannot be read any more, the inventory is empty from then on, as in Ansible: every host leaves, and the next plays match nothing.
Facts and set_fact values stay as they were. See Inventories.
environment
Section titled “environment”environment sets variables for the process a module runs in.
- hosts: web environment: http_proxy: http://proxy.internal:3128 tasks: - name: Fetch the release command: curl -fsSLO https://example.com/app.tar.gz environment: CURL_CA_BUNDLE: /etc/ssl/certs/internal.pemLayers are merged key by key, each one over the previous: the play first, then each enclosing block from the outside in, then the task. Each layer is rendered with the variables of the current loop item.
Values become what Python’s str() makes of them, so 42 becomes "42", true becomes "True" and null becomes "None". An undefined variable inside environment fails the task. A mapping value whose undefined name is ansible_env is left out instead, as in Ansible, since the facts may not be gathered yet.
environment may also be a list of mappings, merged in order. An entry or a value that is omit is left out.
no_log
Section titled “no_log”no_log: true replaces the task’s output with the censored line ansible-playbook prints, on every line it would have shown and at every verbosity level. That covers the ok: and changed: lines, fatal:, UNREACHABLE!, each loop item’s line, and debug output. A loop item’s label becomes (censored due to no_log).
The [ERROR]: block printed above a failure keeps its prefix, such as Task failed: Action failed:, and shows <error censored due to no log> in place of the message. Here Volant differs from ansible-playbook 2.19.12, which censors only an unreachable host’s reason and prints a failed task’s message in full, so a secret in a fail message reaches the terminal.
no_log can be a template. Each host renders it when the task runs. In a loop, one item that hides hides every item, where ansible-core hides each item by its own value.
The task banner and the task’s name are not hidden. The registered variable and the recap keep the real result, so a later task can still read it.
Differences from Ansible
Section titled “Differences from Ansible”delegate_tois rendered once per task, not once per loop item. One batch is one message to one agent over one connection, and a per-item delegate would split a loop across connections.local_actionisdelegate_to: localhostwritten another way, and wins over adelegate_toon the same task.- When the host elected to run a
run_oncetask cannot be reached, the waiting hosts leave the play and the run ends there. Ansible prints one more empty play banner. Neither engine elects another host, and the exit code is the same 4. run_oncecombined withdelegate_factsstores the facts on the delegate, which keepsdelegate_factsmeaning one thing. Ansible’s behavior here was not measured.become,become_userandbecome_methodwritten from the loop item are rendered for each item. Items that escalate the same way run over one link; an item that escalates differently runs over a link of its own, sobecome: "{{ item }}"over[true, false]runs the first item as root and the second as the connecting user, as in Ansible. Such a loop runs its items one at a time.- An
environmentvalue that is not a mapping is skipped with a warning that names the value. Ansible prints the whole stack of layers it sat in instead. - That warning is not censored by
no_log. Ansible does not censor its warning either, so this matches ansible-core, but keep it in mind before you put a secret in anenvironmentthat might not be a mapping.