Loops

    This chapter is all about how to use loops in playbooks.

    To save some typing, repeated tasks can be written in short-hand like so:

    If you have defined a YAML list in a variables file, or the ‘vars’ section, you can also do:

    1. loop: "{{ somelist }}"

    The above would be the equivalent of:

    1. - name: add user testuser1
    2.   user:
    3.     name: "testuser1"
    4.     state: present
    5.     groups: "wheel"
    6. - name: add user testuser2
    7.   user:
    8.     name: "testuser2"
    9.     state: present
    10.     groups: "wheel"

    Note

    Before 2.5 Ansible mainly used the keywords to create loops, the _loop keyword is basically analogous to with_list.

    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:

    1. - name: optimal yum
    2.   yum:
    3.     name: "{{list_of_packages}}"
    4.     state: present
    5.  
    6. - name: non optimal yum, not only slower but might cause issues with interdependencies
    7.   yum:
    8.     name: "{{item}}"
    9.     state: present
    10.   loop: "{{list_of_packages}}"

    Note that the types of items you iterate over do not have to be simple lists of strings.If you have a list of hashes, you can reference subkeys using things like:

    1. - name: add several users
    2.   user:
    3.     name: "{{ item.name }}"
    4.     state: present
    5.     groups: "{{ item.groups }}"
    6.   loop:
    7.     - { name: 'testuser1', groups: 'wheel' }
    8.     - { name: 'testuser2', groups: 'root' }

    Also be aware that when combining Conditionals with a loop, the when: statement is processed separately for each item.See for an example.

    To loop over a dict, use the dict2items Dict Filter:

    1. - name: create a tag dictionary of non-empty tags
    2.   set_fact:
    3.     tags_dict: "{{ (tags_dict|default({}))|combine({item.key: item.value}) }}"
    4.   loop: "{{ tags|dict2items }}"
    5.   vars:
    6.     tags:
    7.       Environment: dev
    8.       Application: payment
    9.       Another: "{{ doesnotexist|default() }}"
    10.   when: item.value != ""

    Here, we don’t want to set empty tags, so we create a dictionary containing only non-empty tags.

    Complex loops

    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:

    1. - name: give users access to multiple databases
    2.   mysql_user:
    3.     name: "{{ item[0] }}"
    4.     priv: "{{ item[1] }}.*:ALL"
    5.     append_privs: yes
    6.     password: "foo"
    7.   loop: "{{ ['alice', 'bob'] |product(['clientdb', 'employeedb', 'providerdb'])|list }}"

    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.

    In Ansible 2.5 a new jinja2 function was introduced named , that offers several benefits over lookup when using the new loop keyword.

    This is better described in the lookup documentation. However, query provides a simpler 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:

    1. loop: "{{ query('inventory_hostnames', 'all') }}"
    2.  
    3. loop: "{{ lookup('inventory_hostnames', 'all', wantlist=True) }}"

    Do-Until Loops

    Sometimes you would want to retry a task until a certain condition is met. Here’s an example:

    1. - shell: /usr/bin/foo
    2.   register: result
    3.   until: result.stdout.find("all systems go") != -1
    4.   retries: 5
    5.   delay: 10

    The above example run the shell module recursively till the module’s result has “all systems go” in its stdout or the task hasbeen retried for 5 times with a delay of 10 seconds. The default value for “retries” is 3 and “delay” is 5.

    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.

    Note

    If the until parameter isn’t defined, the value for the retries parameter is forced to 1.

    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.

    Here is an example of using register with loop:

    This differs from the data structure returned when using register without a loop:

    1. {
    2.     "changed": true,
    3.     "msg": "All items completed",
    4.     "results": [
    5.         {
    6.             "changed": true,
    7.             "cmd": "echo \"one\" ",
    8.             "delta": "0:00:00.003110",
    9.             "end": "2013-12-19 12:00:05.187153",
    10.             "invocation": {
    11.                 "module_args": "echo \"one\"",
    12.                 "module_name": "shell"
    13.             },
    14.             "item": "one",
    15.             "rc": 0,
    16.             "start": "2013-12-19 12:00:05.184043",
    17.             "stderr": "",
    18.             "stdout": "one"
    19.         },
    20.         {
    21.             "changed": true,
    22.             "cmd": "echo \"two\" ",
    23.             "end": "2013-12-19 12:00:05.245502",
    24.             "invocation": {
    25.                 "module_args": "echo \"two\"",
    26.                 "module_name": "shell"
    27.             },
    28.             "item": "two",
    29.             "rc": 0,
    30.             "start": "2013-12-19 12:00:05.242582",
    31.             "stderr": "",
    32.             "stdout": "two"
    33.         }
    34.     ]
    35. }

    Subsequent loops over the registered variable to inspect the results may look like:

    1. - name: Fail if return code is not 0
    2.   fail:
    3.     msg: "The command ({{ item.cmd }}) did not have a 0 return code"
    4.   when: item.rc != 0
    5.   loop: "{{ echo.results }}"

    During iteration, the result of the current item will be placed in the variable:

    1. - shell: echo "{{ item }}"
    2.   loop:
    3.     - one
    4.     - two
    5.   register: echo
    6.   changed_when: echo.stdout != "one"

    Looping over the inventory

    If you wish to loop over the inventory, or just a subset of it, there are multiple ways.One can use a regular loop with the or groups variables, like this:

    1. # show all the hosts in the inventory
    2. - debug:
    3.     msg: "{{ item }}"
    4.   loop: "{{ groups['all'] }}"
    5.  
    6. # show all the hosts in the current play
    7. - debug:
    8.     msg: "{{ item }}"
    9.   loop: "{{ ansible_play_batch }}"

    There is also a specific lookup plugin inventory_hostnames that can be used like this:

    1. # show all the hosts in the inventory
    2. - debug:
    3.     msg: "{{ item }}"
    4.   loop: "{{ query('inventory_hostnames', 'all') }}"
    5.  
    6. # show all the hosts matching the pattern, ie all but the group www
    7. - debug:
    8.     msg: "{{ item }}"
    9.   loop: "{{ query('inventory_hostnames', 'all!www') }}"

    More information on the patterns can be found on Working with Patterns

    New in version 2.1.

    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.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:

    1. # main.yml
    2. - include_tasks: inner.yml
    3.   loop:
    4.     - 1
    5.     - 2
    6.     - 3
    7.   loop_control:
    8.     loop_var: outer_item
    9.  
    10. # inner.yml
    11. - debug:
    12.     msg: "outer item={{ outer_item }} inner item={{ item }}"
    13.   loop:
    14.     - a
    15.     - b
    16.     - c

    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.

    New in version 2.2.

    1. - name: create servers
    2.   digital_ocean:
    3.     name: "{{ item.name }}"
    4.     state: present
    5.   loop:
    6.     - name: server1
    7.       disks: 3gb
    8.       ram: 15Gb
    9.       network:
    10.         nic01: 100Gb
    11.         nic02: 10Gb
    12.         ...
    13.   loop_control:
    14.     label: "{{ item.name }}"

    This will now display just the label field instead of the whole structure per item, it defaults to {{ item }} to display things as usual.

    New in version 2.2.

    Another option to loop control is pause, which allows you to control the time (in seconds) between execution of items in a task loop.:

    1. # main.yml
    2. - name: create servers, pause 3s before creating next
    3.   digital_ocean:
    4.     name: "{{ item }}"
    5.     state: present
    6.   loop:
    7.     - server1
    8.     - server2
    9.   loop_control:
    10.     pause: 3

    New in version 2.5.

    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.:

    Migrating from with_X to loop

    With the release of Ansible 2.5, the recommended way to perform loops is the use the new loop keyword instead of with_X style loops.

    In many cases, loop syntax is better expressed using filters instead of more complex use of query or lookup.

    The following examples will show how to convert many common with_ style loops to loop and filters.

    with_list is directly replaced by loop.

    1. - name: with_list
    2.   debug:
    3.     msg: "{{ item }}"
    4.   with_list:
    5.     - one
    6.     - two
    7.  
    8. - name: with_list -> loop
    9.   debug:
    10.     msg: "{{ item }}"
    11.   loop:
    12.     - one
    13.     - two

    with_items

    with_items is replaced by loop and the flatten filter.

    1.   debug:
    2.     msg: "{{ item }}"
    3.   with_items: "{{ items }}"
    4.  
    5. - name: with_items -> loop
    6.   debug:
    7.     msg: "{{ item }}"
    8.   loop: "{{ items|flatten(levels=1) }}"

    with_indexed_items

    with_indexed_items is replaced by , the flatten filter and loop_control.index_var.

    1. - name: with_indexed_items
    2.   debug:
    3.     msg: "{{ item.0 }} - {{ item.1 }}"
    4.   with_indexed_items: "{{ items }}"
    5.  
    6. - name: with_indexed_items -> loop
    7.   debug:
    8.     msg: "{{ index }} - {{ item }}"
    9.   loop: "{{ items|flatten(levels=1) }}"
    10.   loop_control:
    11.     index_var: index

    with_flattened is replaced by loop and the flatten filter.

    1. - name: with_flattened
    2.   debug:
    3.     msg: "{{ item }}"
    4.   with_flattened: "{{ items }}"
    5.  
    6. - name: with_flattened -> loop
    7.   debug:
    8.     msg: "{{ item }}"
    9.   loop: "{{ items|flatten }}"

    with_together

    with_together is replaced by loop and the zip filter.

    1. - name: with_together
    2.   debug:
    3.     msg: "{{ item.0 }} - {{ item.1 }}"
    4.   with_together:
    5.     - "{{ list_one }}"
    6.     - "{{ list_two }}"
    7.  
    8. - name: with_together -> loop
    9.   debug:
    10.     msg: "{{ item.0 }} - {{ item.1 }}"
    11.   loop: "{{ list_one|zip(list_two)|list }}"

    with_dict

    with_dict can be substituted by loop and either the dictsort or dict2items filters.

    1. - name: with_dict
    2.   debug:
    3.     msg: "{{ item.key }} - {{ item.value }}"
    4.   with_dict: "{{ dictionary }}"
    5.  
    6. - name: with_dict -> loop (option 1)
    7.   debug:
    8.     msg: "{{ item.key }} - {{ item.value }}"
    9.   loop: "{{ dictionary|dict2items }}"
    10.  
    11. - name: with_dict -> loop (option 2)
    12.   debug:
    13.     msg: "{{ item.0 }} - {{ item.1 }}"
    14.   loop: "{{ dictionary|dictsort }}"

    with_sequence is replaced by loop and the range function, and potentially the format filter.

    1. - name: with_sequence
    2.   debug:
    3.     msg: "{{ item }}"
    4.   with_sequence: start=0 end=4 stride=2 format=testuser%02x
    5.  
    6. - name: with_sequence -> loop
    7.   debug:
    8.     msg: "{{ 'testuser%02x' | format(item) }}"
    9.   # range is exclusive of the end point
    10.   loop: "{{ range(0, 4 + 1, 2)|list }}"

    with_subelements

    with_subelements is replaced by loop and the subelements filter.

    1. - name: with_subelements
    2.   debug:
    3.     msg: "{{ item.0.name }} - {{ item.1 }}"
    4.   with_subelements:
    5.     - "{{ users }}"
    6.     - mysql.hosts
    7.  
    8. - name: with_subelements -> loop
    9.   debug:
    10.     msg: "{{ item.0.name }} - {{ item.1 }}"
    11.   loop: "{{ users|subelements('mysql.hosts') }}"

    with_nested/with_cartesian

    with_nested and with_cartesian are replaced by loop and the product filter.

    with_random_choice is replaced by just use of the random filter, without need of .

    1. - name: with_random_choice
    2.   debug:
    3.     msg: "{{ item }}"
    4.   with_random_choice: "{{ my_list }}"
    5.  
    6. - name: with_random_choice -> loop (No loop is needed here)
    7.   debug:
    8.     msg: "{{ my_list|random }}"
    9.   tags: random
    • An introduction to playbooks
    • Roles
    • Playbook organization by roles
    • Best practices in playbooks
    • Conditionals
    • Conditional statements in playbooks
    • All about variables
    • User Mailing List
    • Have a question? Stop by the google group!

    • ansible IRC chat channel