W3cubDocs

/Ansible 2.10

ansible.builtin.items – list of items

Note

This module is part of ansible-base and included in all Ansible installations. In most cases, you can use the short module name items even without specifying the collections: keyword. Despite that, we recommend you use the FQCN for easy linking to the module documentation and to avoid conflicting with other collections that may have the same module name.

Synopsis

  • this lookup returns a list of items given to it, if any of the top level items is also a list it will flatten it, but it will not recurse

Parameters

Parameter Choices/Defaults Configuration Comments
_terms
string / required
list of items

Notes

Note

  • this is the standard lookup used for loops in most examples
  • check out the ‘flattened’ lookup for recursive flattening
  • if you do not want flattening nor any other transformation look at the ‘list’ lookup.

Examples

- name: "loop through list"
  debug:
    msg: "An item: {{ item }}"
  with_items:
    - 1
    - 2
    - 3

- name: add several users
  user:
    name: "{{ item }}"
    groups: "wheel"
    state: present
  with_items:
     - testuser1
     - testuser2

- name: "loop through list from a variable"
  debug:
    msg: "An item: {{ item }}"
  with_items: "{{ somelist }}"

- name: more complex items to add several users
  user:
    name: "{{ item.name }}"
    uid: "{{ item.uid }}"
    groups: "{{ item.groups }}"
    state: present
  with_items:
     - { name: testuser1, uid: 1002, groups: "wheel, staff" }
     - { name: testuser2, uid: 1003, groups: staff }

Return Values

Common return values are documented here, the following are the fields unique to this lookup:

Key Returned Description
_raw
list / elements=string
success
once flattened list


Authors

  • Michael DeHaan

© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.10/collections/ansible/builtin/items_lookup.html