Loops and retries
loop, with_items and loop_control, and how until, retries and delay repeat a task.
This page answers how to repeat a task over a list of items with loop and with_<lookup>, and how to run a task again until it succeeds with until, retries and delay.
- name: Create the service accounts command: useradd --system {{ item }} loop: - app - worker loop_control: label: "{{ item }}" register: accountsloop and with_items cannot both appear on the same task. with_items flattens one level of nested lists and loop does not, as in Ansible. Registering a looped task collects a results list with one entry per item.
loop_control reads loop_var, label, index_var, pause, extended, extended_allitems and break_when. A sub-key ansible-core does not know is rejected when the playbook loads. Every with_<lookup> form runs. See Keywords and with_ loops.
with_ loops
Section titled “with_ loops”with_<name> is loop: "{{ lookup('<name>', *terms, wantlist=True) }}", and it runs for every lookup plugin ansible-core has:
| Lookup | Examples |
|---|---|
The twenty-five of ansible.builtin |
with_dict, with_nested, with_subelements, with_sequence |
Lookups that ansible-core redirects to community.general |
with_flattened, with_cartesian, with_filetree |
| A collection’s lookup, under its full name | with_community.general.dependent |
A plugin in a lookup_plugins/ directory beside the playbook or a role |
the plugin’s file name, as with_<name> |
A builtin lookup is also accepted as with_ansible.builtin.<name> and with_ansible.legacy.<name>.
The controller’s ansible-core says whether a name is a lookup, before the first connection. A with_ name that is none fails the playbook with 'with_xyz' is not a valid attribute for a Task, as in Ansible. A task with two loops fails with duplicate loop in task: <name>, and a with_ key with no value with you must specify a value when using with_<name>.
A lookup that raises fails the task with the plugin’s own sentence. A lookup that Volant runs itself, in Rust (file, unvault, vars, pipe, template and first_found) fails with The lookup plugin '<name>' failed: <reason> and ansible-core’s chain, also in a when: and in a template file. vars words it No variable named '<name>' was found., with no plugin part. A loop value that is one template reading an undefined variable fails with 'name' is undefined. A list whose element reads an undefined variable fails with the engine’s sentence for it, without the chain that Ansible prints.
Rendering each item
Section titled “Rendering each item”A loop renders an item’s arguments, when, keywords and label when it reaches the item, not before the loop starts.
- An item that fails to render fails alone, as
failed: [h] (item=2). The items after it still run, and the task ends withOne or more items failed. - A
break_whenthat ends the loop first hides the render errors of the items after it. - A
debugorset_factloop with aloop_control.pauserenders each item after the pause, sonow()reads the time the item runs, and a loopedset_factstill hands what it set to the items after it. - A
loop_control.labelthat reads an undefined variable fails its item after the module ran.
with_first_found and with_fileglob
Section titled “with_first_found and with_fileglob”- name: Distribute the matching config copy: src: "{{ item }}" dest: /etc/app/config.yml with_first_found: - "{{ ansible_distribution }}.yml" - default.yml
- name: Copy every image copy: src: "{{ item }}" dest: /var/lib/app/images/ with_fileglob: - "images/*.tar.gz"Both loop over a lookup, the way any with_<name> form does: with_first_found walks its terms until one names a file that exists, and with_fileglob collects every match of a glob pattern. with_first_found also searches a subdirectory of each search entry before the entry itself: templates/ when the task’s action names template, vars/ when it names include_vars, files/ otherwise, the same directory a plain template: or include_vars: task would search on its own.
Finding nothing fails the task with ansible-core’s own sentence, No file was found when using first_found., unless the term is a mapping with skip: true, in which case the loop runs empty. A term that renders undefined is dropped rather than failing the whole lookup, and so is an undefined value inside the list that a loop value written as one string renders to, which is what lets a role read a fact no host has set yet and still reach its when. A path either lookup finds that still holds a template marker ({{, {% or {#) is refused by name rather than rendered a second time.
A path a lookup found on the controller is the playbook’s own content; an item built in part from a host value, such as a term that reads ansible_distribution, is bound as data, the same as an item out of a loop: over a registered value.
Retrying with until
Section titled “Retrying with until”- name: Wait for the service to answer command: curl -fsS http://localhost:8080/health register: health until: health.rc == 0 retries: 10 delay: 3until runs a task again until its expression holds.
retriesis the number of retries after the first attempt, not the total: the task runs up toretries + 1times. It is 3 when onlyuntilis written, for up to four runs.- A
retriesbelow 1 turns retrying off: the task runs once and its result has noattempts. - Volant waits
delayseconds, 5 by default, after each of the firstretriesfailed runs, never after the last one. - The result carries the number of retries actually run under
attempts, at mostretries. A task that runs out of retries has failed, even if the module itself succeeded. With afailed_when, its result on the last run decides instead:failed_when: falselets the task pass, and the registered result still saysfailed: true. retrieswithoutuntilrepeats the task while its result is failed.- A task backed by an action plugin (
copy,dnf,package…) retries its whole sequence of sub-tasks from the start on each attempt, with a fresh plugin and any file sent again;untilreads only the last sub-task’s result.
A looping task retries each item on its own and finishes one item’s attempts before starting the next.
until, retries and delay are rejected on include_tasks and include_role, before the first connection. Ansible rejects them there too, when it loads the playbook. include_vars is an ordinary module and retries like any other task.
Differences from Ansible
Section titled “Differences from Ansible”- An
untilexpression that cannot be evaluated is reported with ansible-core’s prefix and Volant’s own message, the same way a failingwhenis. - A
loop_control.labelthat fails for a reason other than an undefined variable, such as a lookup that raises, fails the task before any item runs. ansible-core ends the task after that item has run.