2018-03-14 19:44:21 +00:00
.. _playbooks_loops:
2013-09-29 21:02:53 +00:00
Loops
=====
2013-09-25 05:18:43 +00:00
2013-10-05 17:50:53 +00:00
Often you'll want to do many things in one task, such as create a lot of users, install a lot of packages, or
repeat a polling step until a certain result is reached.
This chapter is all about how to use loops in playbooks.
2013-09-25 04:26:14 +00:00
2013-12-26 19:32:01 +00:00
.. contents :: Topics
2013-10-04 22:34:39 +00:00
.. _standard_loops:
2013-09-25 04:26:14 +00:00
2013-09-29 21:02:53 +00:00
Standard Loops
`` ` ` ` ` ` ` ` ` ` ` ``
2012-05-13 15:00:02 +00:00
To save some typing, repeated tasks can be written in short-hand like so::
2013-03-02 16:47:43 +00:00
- name: add several users
2017-03-06 22:39:07 +00:00
user:
name: "{{ item }}"
state: present
groups: "wheel"
move from with_<lookup>: to loop:
- old functionality is still available direct lookup use, the following are equivalent
with_nested: [[1,2,3], ['a','b','c']]
loop: "{{lookup('nested', [1,2,3], ['a','b','c'])}}"
- avoid squashing with 'loop:'
- fixed test to use new intenal attributes
- removed most of 'lookup docs' as these now reside in the plugins
2017-09-17 03:32:34 +00:00
loop:
2012-05-13 15:00:02 +00:00
- testuser1
- testuser2
2012-08-01 02:19:04 +00:00
If you have defined a YAML list in a variables file, or the 'vars' section, you can also do::
move from with_<lookup>: to loop:
- old functionality is still available direct lookup use, the following are equivalent
with_nested: [[1,2,3], ['a','b','c']]
loop: "{{lookup('nested', [1,2,3], ['a','b','c'])}}"
- avoid squashing with 'loop:'
- fixed test to use new intenal attributes
- removed most of 'lookup docs' as these now reside in the plugins
2017-09-17 03:32:34 +00:00
loop: "{{ somelist }}"
2012-08-01 02:19:04 +00:00
2012-05-13 15:00:02 +00:00
The above would be the equivalent of::
- name: add user testuser1
2017-03-06 22:39:07 +00:00
user:
name: "testuser1"
state: present
groups: "wheel"
2012-05-13 15:00:02 +00:00
- name: add user testuser2
2017-03-06 22:39:07 +00:00
user:
name: "testuser2"
state: present
groups: "wheel"
2012-05-13 15:00:02 +00:00
2017-12-07 14:25:46 +00:00
.. note :: Before 2.5 Ansible mainly used the `` with_<lookup> `` keywords to create loops, the `loop` keyword is basically analogous to `` with_list `` .
2012-05-13 15:00:02 +00:00
move from with_<lookup>: to loop:
- old functionality is still available direct lookup use, the following are equivalent
with_nested: [[1,2,3], ['a','b','c']]
loop: "{{lookup('nested', [1,2,3], ['a','b','c'])}}"
- avoid squashing with 'loop:'
- fixed test to use new intenal attributes
- removed most of 'lookup docs' as these now reside in the plugins
2017-09-17 03:32:34 +00:00
Some plugins like, the yum and apt modules can take lists directly to their options, this is more optimal than looping over the task.
See each action's documentation for details, for now here is an example::
- name: optimal yum
2018-02-03 11:32:11 +00:00
yum:
name: "{{list_of_packages}}"
state: present
move from with_<lookup>: to loop:
- old functionality is still available direct lookup use, the following are equivalent
with_nested: [[1,2,3], ['a','b','c']]
loop: "{{lookup('nested', [1,2,3], ['a','b','c'])}}"
- avoid squashing with 'loop:'
- fixed test to use new intenal attributes
- removed most of 'lookup docs' as these now reside in the plugins
2017-09-17 03:32:34 +00:00
- name: non optimal yum, not only slower but might cause issues with interdependencies
2018-02-03 11:32:11 +00:00
yum:
name: "{{item}}"
state: present
move from with_<lookup>: to loop:
- old functionality is still available direct lookup use, the following are equivalent
with_nested: [[1,2,3], ['a','b','c']]
loop: "{{lookup('nested', [1,2,3], ['a','b','c'])}}"
- avoid squashing with 'loop:'
- fixed test to use new intenal attributes
- removed most of 'lookup docs' as these now reside in the plugins
2017-09-17 03:32:34 +00:00
loop: "{{list_of_packages}}"
Note that the types of items you iterate over do not have to be simple lists of strings.
2012-10-16 22:58:31 +00:00
If you have a list of hashes, you can reference subkeys using things like::
2013-05-29 22:05:14 +00:00
- name: add several users
2017-03-06 22:39:07 +00:00
user:
name: "{{ item.name }}"
state: present
groups: "{{ item.groups }}"
move from with_<lookup>: to loop:
- old functionality is still available direct lookup use, the following are equivalent
with_nested: [[1,2,3], ['a','b','c']]
loop: "{{lookup('nested', [1,2,3], ['a','b','c'])}}"
- avoid squashing with 'loop:'
- fixed test to use new intenal attributes
- removed most of 'lookup docs' as these now reside in the plugins
2017-09-17 03:32:34 +00:00
loop:
2013-05-29 22:05:14 +00:00
- { name: 'testuser1', groups: 'wheel' }
- { name: 'testuser2', groups: 'root' }
2012-10-16 22:58:31 +00:00
2018-04-07 09:13:19 +00:00
Also be aware that when combining :doc: `playbooks_conditionals` with a loop, the `` when: `` statement is processed separately for each item.
move from with_<lookup>: to loop:
- old functionality is still available direct lookup use, the following are equivalent
with_nested: [[1,2,3], ['a','b','c']]
loop: "{{lookup('nested', [1,2,3], ['a','b','c'])}}"
- avoid squashing with 'loop:'
- fixed test to use new intenal attributes
- removed most of 'lookup docs' as these now reside in the plugins
2017-09-17 03:32:34 +00:00
See :ref: `the_when_statement` for an example.
2015-03-06 21:35:49 +00:00
2018-04-07 09:13:19 +00:00
To loop over a dict, use the `` dict2items `` :ref: `dict_filter` ::
- name: create a tag dictionary of non-empty tags
set_fact:
tags_dict: "{{ (tags_dict|default({}))|combine({item.key: item.value}) }}"
2018-04-25 17:55:34 +00:00
loop: "{{ tags|dict2items }}"
2018-04-07 09:13:19 +00:00
vars:
tags:
Environment: dev
Application: payment
Another: "{{ doesnotexist|default() }}"
when: item.value != ""
Here, we don't want to set empty tags, so we create a dictionary containing only non-empty tags.
2017-08-18 20:02:35 +00:00
move from with_<lookup>: to loop:
- old functionality is still available direct lookup use, the following are equivalent
with_nested: [[1,2,3], ['a','b','c']]
loop: "{{lookup('nested', [1,2,3], ['a','b','c'])}}"
- avoid squashing with 'loop:'
- fixed test to use new intenal attributes
- removed most of 'lookup docs' as these now reside in the plugins
2017-09-17 03:32:34 +00:00
.. _complex_loops:
2013-10-04 22:34:39 +00:00
move from with_<lookup>: to loop:
- old functionality is still available direct lookup use, the following are equivalent
with_nested: [[1,2,3], ['a','b','c']]
loop: "{{lookup('nested', [1,2,3], ['a','b','c'])}}"
- avoid squashing with 'loop:'
- fixed test to use new intenal attributes
- removed most of 'lookup docs' as these now reside in the plugins
2017-09-17 03:32:34 +00:00
Complex loops
`` ` ` ` ` ` ` ` ` ` ``
2013-07-15 04:28:02 +00:00
move from with_<lookup>: to loop:
- old functionality is still available direct lookup use, the following are equivalent
with_nested: [[1,2,3], ['a','b','c']]
loop: "{{lookup('nested', [1,2,3], ['a','b','c'])}}"
- avoid squashing with 'loop:'
- fixed test to use new intenal attributes
- removed most of 'lookup docs' as these now reside in the plugins
2017-09-17 03:32:34 +00:00
Sometimes you need more than what a simple list provides, you can use Jinja2 expressions to create complex lists:
For example, using the 'nested' lookup, you can combine lists::
2013-07-15 04:28:02 +00:00
2013-07-19 13:13:30 +00:00
- name: give users access to multiple databases
2017-03-06 22:39:07 +00:00
mysql_user:
name: "{{ item[0] }}"
priv: "{{ item[1] }}.*:ALL"
append_privs: yes
password: "foo"
2018-06-01 14:37:21 +00:00
loop: "{{ ['alice', 'bob'] |product(['clientdb', 'employeedb', 'providerdb'])|list }}"
2013-01-08 20:13:25 +00:00
2017-12-07 14:25:46 +00:00
.. note :: `` with_ `` loops are actually a combination of things `` with_ `` + `` lookup() `` , even `` items `` is a lookup. `` loop `` can be used in the same way as shown above.
2013-10-04 22:34:39 +00:00
2018-04-25 17:55:34 +00:00
Using lookup vs query with loop
`` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ``
In Ansible 2.5 a new jinja2 function was introduced named :ref: `query` , that offers several benefits over `` lookup `` when using the new `` loop `` keyword.
This is described more in the lookup documentation, however, `` query `` provides a more simple interface and a more predictable output from lookup plugins, ensuring better compatibility with `` loop `` .
In certain situations the `` lookup `` function may not return a list which `` loop `` requires.
The following invocations are equivalent, using `` wantlist=True `` with `` lookup `` to ensure a return type of a list::
2018-06-01 14:37:21 +00:00
loop: "{{ query('inventory_hostnames', 'all') }}"
2018-04-25 17:55:34 +00:00
2018-06-01 14:37:21 +00:00
loop: "{{ lookup('inventory_hostnames', 'all', wantlist=True) }}"
2018-04-25 17:55:34 +00:00
2013-10-04 22:34:39 +00:00
.. _do_until_loops:
2013-09-29 21:02:53 +00:00
Do-Until Loops
`` ` ` ` ` ` ` ` ` ` ` ``
2013-09-03 04:08:00 +00:00
2016-09-30 14:01:56 +00:00
.. versionadded :: 1.4
2013-10-14 12:24:20 +00:00
2013-09-29 21:02:53 +00:00
Sometimes you would want to retry a task until a certain condition is met. Here's an example::
2016-09-30 14:01:56 +00:00
2017-04-27 08:30:45 +00:00
- shell: /usr/bin/foo
2013-09-29 21:02:53 +00:00
register: result
2013-10-03 20:28:29 +00:00
until: result.stdout.find("all systems go") != -1
2013-09-29 21:02:53 +00:00
retries: 5
delay: 10
2013-08-12 13:49:34 +00:00
2014-05-03 15:59:50 +00:00
The above example run the shell module recursively till the module's result has "all systems go" in its stdout or the task has
2013-09-29 21:02:53 +00:00
been retried for 5 times with a delay of 10 seconds. The default value for "retries" is 3 and "delay" is 5.
2012-08-01 02:19:04 +00:00
2013-09-29 21:02:53 +00:00
The task returns the results returned by the last task run. The results of individual retries can be viewed by -vv option.
The registered variable will also have a new key "attempts" which will have the number of the retries for the task.
2012-08-01 02:19:04 +00:00
2017-12-07 14:25:46 +00:00
.. note :: If the `` until `` parameter isn't defined, the value for the `` retries `` parameter is forced to 1.
2017-08-30 18:17:20 +00:00
2013-12-19 18:11:00 +00:00
Using register with a loop
`` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ``
2017-02-02 23:02:28 +00:00
After using `` register `` with a loop, the data structure placed in the variable will contain a `` results `` attribute that is a list of all responses from the module.
2013-12-19 18:11:00 +00:00
2018-02-02 13:33:13 +00:00
Here is an example of using `` register `` with `` loop `` ::
2013-12-19 18:11:00 +00:00
2017-03-06 22:39:07 +00:00
- shell: "echo {{ item }}"
move from with_<lookup>: to loop:
- old functionality is still available direct lookup use, the following are equivalent
with_nested: [[1,2,3], ['a','b','c']]
loop: "{{lookup('nested', [1,2,3], ['a','b','c'])}}"
- avoid squashing with 'loop:'
- fixed test to use new intenal attributes
- removed most of 'lookup docs' as these now reside in the plugins
2017-09-17 03:32:34 +00:00
loop:
2017-03-06 22:39:07 +00:00
- "one"
- "two"
2013-12-19 18:11:00 +00:00
register: echo
2014-01-09 00:17:36 +00:00
This differs from the data structure returned when using `` register `` without a loop::
2013-12-19 18:11:00 +00:00
{
"changed": true,
"msg": "All items completed",
"results": [
{
"changed": true,
"cmd": "echo \"one\" ",
"delta": "0:00:00.003110",
"end": "2013-12-19 12:00:05.187153",
"invocation": {
"module_args": "echo \"one\"",
"module_name": "shell"
},
"item": "one",
"rc": 0,
"start": "2013-12-19 12:00:05.184043",
"stderr": "",
"stdout": "one"
},
{
"changed": true,
"cmd": "echo \"two\" ",
"delta": "0:00:00.002920",
"end": "2013-12-19 12:00:05.245502",
"invocation": {
"module_args": "echo \"two\"",
"module_name": "shell"
},
"item": "two",
"rc": 0,
"start": "2013-12-19 12:00:05.242582",
"stderr": "",
"stdout": "two"
}
]
}
Subsequent loops over the registered variable to inspect the results may look like::
- name: Fail if return code is not 0
fail:
msg: "The command ({{ item.cmd }}) did not have a 0 return code"
when: item.rc != 0
move from with_<lookup>: to loop:
- old functionality is still available direct lookup use, the following are equivalent
with_nested: [[1,2,3], ['a','b','c']]
loop: "{{lookup('nested', [1,2,3], ['a','b','c'])}}"
- avoid squashing with 'loop:'
- fixed test to use new intenal attributes
- removed most of 'lookup docs' as these now reside in the plugins
2017-09-17 03:32:34 +00:00
loop: "{{ echo.results }}"
2013-12-19 18:11:00 +00:00
2017-02-28 20:34:39 +00:00
During iteration, the result of the current item will be placed in the variable::
2017-02-02 23:02:28 +00:00
- shell: echo "{{ item }}"
move from with_<lookup>: to loop:
- old functionality is still available direct lookup use, the following are equivalent
with_nested: [[1,2,3], ['a','b','c']]
loop: "{{lookup('nested', [1,2,3], ['a','b','c'])}}"
- avoid squashing with 'loop:'
- fixed test to use new intenal attributes
- removed most of 'lookup docs' as these now reside in the plugins
2017-09-17 03:32:34 +00:00
loop:
2017-02-02 23:02:28 +00:00
- one
- two
register: echo
changed_when: echo.stdout != "one"
2015-10-23 14:31:57 +00:00
2015-12-01 23:21:10 +00:00
Looping over the inventory
`` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ``
2018-03-30 16:32:29 +00:00
If you wish to loop over the inventory, or just a subset of it, there are multiple ways.
move from with_<lookup>: to loop:
- old functionality is still available direct lookup use, the following are equivalent
with_nested: [[1,2,3], ['a','b','c']]
loop: "{{lookup('nested', [1,2,3], ['a','b','c'])}}"
- avoid squashing with 'loop:'
- fixed test to use new intenal attributes
- removed most of 'lookup docs' as these now reside in the plugins
2017-09-17 03:32:34 +00:00
One can use a regular `` loop `` with the `` ansible_play_batch `` or `` groups `` variables, like this::
2015-12-01 23:21:10 +00:00
# show all the hosts in the inventory
2017-03-06 22:39:07 +00:00
- debug:
msg: "{{ item }}"
2018-02-02 12:52:28 +00:00
loop: "{{ groups['all'] }}"
2015-12-01 23:21:10 +00:00
# show all the hosts in the current play
2017-03-06 22:39:07 +00:00
- debug:
msg: "{{ item }}"
2018-02-02 12:52:28 +00:00
loop: "{{ ansible_play_batch }}"
2015-12-01 23:21:10 +00:00
2016-04-28 13:18:32 +00:00
There is also a specific lookup plugin `` inventory_hostnames `` that can be used like this::
2015-12-01 23:21:10 +00:00
# show all the hosts in the inventory
2017-03-06 22:39:07 +00:00
- debug:
msg: "{{ item }}"
2018-04-25 17:55:34 +00:00
loop: "{{ query('inventory_hostnames', 'all') }}"
2015-12-01 23:21:10 +00:00
# show all the hosts matching the pattern, ie all but the group www
2017-03-06 22:39:07 +00:00
- debug:
msg: "{{ item }}"
2018-04-25 17:55:34 +00:00
loop: "{{ query('inventory_hostnames', 'all!www') }}"
2015-12-01 23:21:10 +00:00
More information on the patterns can be found on :doc: `intro_patterns`
2015-10-23 07:27:09 +00:00
.. _loop_control:
2015-10-23 14:31:57 +00:00
2015-10-23 07:27:09 +00:00
Loop Control
`` ` ` ` ` ` ` ` ` ``
2015-10-23 14:31:57 +00:00
2016-09-30 14:01:56 +00:00
.. versionadded :: 2.1
2015-10-23 14:31:57 +00:00
move from with_<lookup>: to loop:
- old functionality is still available direct lookup use, the following are equivalent
with_nested: [[1,2,3], ['a','b','c']]
loop: "{{lookup('nested', [1,2,3], ['a','b','c'])}}"
- avoid squashing with 'loop:'
- fixed test to use new intenal attributes
- removed most of 'lookup docs' as these now reside in the plugins
2017-09-17 03:32:34 +00:00
In 2.0 you are again able to use loops and task includes (but not playbook includes). This adds the ability to loop over the set of tasks in one shot.
2017-12-07 14:25:46 +00:00
Ansible by default sets the loop variable `` item `` for each loop, which causes these nested loops to overwrite the value of `` item `` from the "outer" loops.
As of Ansible 2.1, the `` loop_control `` option can be used to specify the name of the variable to be used for the loop::
2015-10-23 14:31:57 +00:00
2015-10-23 07:27:09 +00:00
# main.yml
2017-09-17 18:02:46 +00:00
- include_tasks: inner.yml
move from with_<lookup>: to loop:
- old functionality is still available direct lookup use, the following are equivalent
with_nested: [[1,2,3], ['a','b','c']]
loop: "{{lookup('nested', [1,2,3], ['a','b','c'])}}"
- avoid squashing with 'loop:'
- fixed test to use new intenal attributes
- removed most of 'lookup docs' as these now reside in the plugins
2017-09-17 03:32:34 +00:00
loop:
2015-10-23 14:31:57 +00:00
- 1
- 2
- 3
2015-10-23 07:27:09 +00:00
loop_control:
loop_var: outer_item
# inner.yml
2017-03-06 22:39:07 +00:00
- debug:
msg: "outer item={{ outer_item }} inner item={{ item }}"
move from with_<lookup>: to loop:
- old functionality is still available direct lookup use, the following are equivalent
with_nested: [[1,2,3], ['a','b','c']]
loop: "{{lookup('nested', [1,2,3], ['a','b','c'])}}"
- avoid squashing with 'loop:'
- fixed test to use new intenal attributes
- removed most of 'lookup docs' as these now reside in the plugins
2017-09-17 03:32:34 +00:00
loop:
2015-10-23 07:27:09 +00:00
- a
- b
- c
2015-10-23 14:31:57 +00:00
2015-10-23 07:27:09 +00:00
.. note :: If Ansible detects that the current loop is using a variable which has already been defined, it will raise an error to fail the task.
2015-10-23 14:31:57 +00:00
2016-09-30 14:01:56 +00:00
.. versionadded :: 2.2
2017-12-07 14:25:46 +00:00
When using complex data structures for looping the display might get a bit too "busy", this is where the `` label `` directive comes to help::
2016-08-31 20:09:37 +00:00
- name: create servers
2017-03-06 22:39:07 +00:00
digital_ocean:
name: "{{ item.name }}"
state: present
move from with_<lookup>: to loop:
- old functionality is still available direct lookup use, the following are equivalent
with_nested: [[1,2,3], ['a','b','c']]
loop: "{{lookup('nested', [1,2,3], ['a','b','c'])}}"
- avoid squashing with 'loop:'
- fixed test to use new intenal attributes
- removed most of 'lookup docs' as these now reside in the plugins
2017-09-17 03:32:34 +00:00
loop:
2016-08-31 20:09:37 +00:00
- name: server1
disks: 3gb
ram: 15Gb
2016-10-21 13:58:09 +00:00
network:
2016-08-31 20:09:37 +00:00
nic01: 100Gb
nic02: 10Gb
...
loop_control:
2017-12-19 11:26:05 +00:00
label: "{{ item.name }}"
2016-08-31 20:09:37 +00:00
2017-12-19 11:26:05 +00:00
This will now display just the `` label `` field instead of the whole structure per `` item `` , it defaults to `` {{ item }} `` to display things as usual.
2016-08-31 20:09:37 +00:00
2016-09-30 14:01:56 +00:00
.. versionadded :: 2.2
2017-12-07 14:25:46 +00:00
Another option to loop control is `` pause `` , which allows you to control the time (in seconds) between execution of items in a task loop.::
2016-08-31 20:09:37 +00:00
# main.yml
- name: create servers, pause 3s before creating next
2017-03-06 22:39:07 +00:00
digital_ocean:
name: "{{ item }}"
state: present
move from with_<lookup>: to loop:
- old functionality is still available direct lookup use, the following are equivalent
with_nested: [[1,2,3], ['a','b','c']]
loop: "{{lookup('nested', [1,2,3], ['a','b','c'])}}"
- avoid squashing with 'loop:'
- fixed test to use new intenal attributes
- removed most of 'lookup docs' as these now reside in the plugins
2017-09-17 03:32:34 +00:00
loop:
2016-08-31 20:09:37 +00:00
- server1
- server2
2016-09-30 14:01:56 +00:00
loop_control:
2016-08-31 20:09:37 +00:00
pause: 3
2018-04-05 18:06:14 +00:00
.. versionadded :: 2.5
2018-01-26 21:29:04 +00:00
If you need to keep track of where you are in a loop, you can use the `` index_var `` option to loop control to specify a variable name to contain the current loop index.::
- name: count our fruit
debug:
msg: "{{ item }} with index {{ my_idx }}"
loop:
- apple
- banana
- pear
loop_control:
index_var: my_idx
2015-10-23 14:31:57 +00:00
2018-06-01 14:37:21 +00:00
Migrating from with_X to loop
`` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ``
.. include :: shared_snippets/with2loop.txt
2013-10-13 12:54:36 +00:00
2013-10-05 16:31:16 +00:00
.. seealso ::
:doc: `playbooks`
An introduction to playbooks
2017-06-06 21:39:48 +00:00
:doc: `playbooks_reuse_roles`
2013-10-05 16:31:16 +00:00
Playbook organization by roles
:doc: `playbooks_best_practices`
Best practices in playbooks
:doc: `playbooks_conditionals`
Conditional statements in playbooks
:doc: `playbooks_variables`
All about variables
2018-07-21 13:48:47 +00:00
`User Mailing List <https://groups.google.com/group/ansible-devel> `_
2013-10-05 16:31:16 +00:00
Have a question? Stop by the google group!
`irc.freenode.net <http://irc.freenode.net> `_
#ansible IRC chat channel