Ansible with_items

Introduction to Ansible with_items

Ansible with_items is a lookup type plugins which is used to return list items passed into it. Actual plugin name is items. Ansible have different plugin types, further these plugin types have various plugins in each category. One such plugin type is lookup, which allows ansible to access data from outside resources. The data provided by these plugins is converted to standard templating (Jinja2) system in Ansible and used to load variables or templates with any data from those systems. One such lookup plugin is items, which is used with keyword with_items.

What is Ansible with_items?

Ansible with_items plugin is a widely used plugin. You will use it whenever you need loop arrangement in your playbook, because this is the standard lookup used mostly. When we pass a list of items to a task, then task will be performed for all items in that list. If a high-level item has also another list, then that list will be flattened and Ansible will not perform recursion for it. This feature is not available in it. Because that is done by another plugin named list lookup. You can use it to achieve recursion.

Also, you can pass multiple entries in a single item to pass data to parameters when you are running a task which need more than one parameter like while adding a user, you might need to pass userid, name, groups etc. This flexibility makes it more suitable in real world scenarios. Also, note that all the variable realization and item parsing will be done on local Ansible controller node, like any other plugin.

How does Ansible with_item works?

Ansible with_items is a keyword which you will use in playbook and provide a list of items under it. These are some scenarios when you have a simple list, an item is list is also a list, each item in list is a combination of few variables.

Let us see how its syntax will look:

1. A simple list will be like below and used in a task as follows.

- name: ASimple List
debug:
msg: "My Fruit is {{ item }}"
with_items:
- apple
- banana
- orange
- pineapple
- grapes

2. A list where an item has another list inside it, it will look like as follows.

- name: A List with An Item Having Another List
debug: var=item
with_items:
- apple
- [eagle, falcon] - lion

3. A list where an item has a list of variables inside it. This will look like as follows.

- name: A List where multiple variables are passed in an item of list
user:
name: "{{ item.name }}"
uid: "{{ item.uid }}"
groups: "{{ item.groups }}"
state: present
with_items:
- { name: sample1, uid: 2001, groups: "HR" }
- { name: sample2, uid: 2002, groups: "Finance" }

Now we will see some real usage of Ansible with_items in playbooks and what will be the output of such execution.

Examples of Ansible with_items

Now by using examples, we will see about Ansible with_items plugin, which you might have to use in day to day operations. We will take some examples, but before going there, we first see our lab, we used for testing purpose. In the practice lab, we have Ansible control server “ansible-controller” and two target machines named host-two and host-one.

We will create playbooks and run Ansible commands on ansible-controller node and see the results on remote hosts.

Example #1

In this example, we will see how different lists will be treated by Ansible with_items. We will provide different type of lists to it and use Ansible debug module to check the output. For this purpose we have a playbook like below.

Code:

---
- hosts: localhost
tasks:
- name : Here we are providing a simple list.
debug:
msg: Current Fruit item is {{ item }}
with_items:
- apple
- banana
- name: Here we are providing a list which have another list as item
debug:
msg: current value is {{ item }}
with_items:
- Tiger
- [Eagle,Falcon] - name: Here we are providing a list which have items containing multiple values
debug:
msg: "current first value is {{ item.first }} and second value is {{ item.second }}"
with_items:
- { first: lemon, second: carrot }
- { first: cow, second: goat }

Run this playbook like below:

ansible-playbook  ansible_with_items_lists.yaml

In the output we can see the how different lists are seen by Ansible with_items plugin.

Output:

Example #2

In this example, we will do some tasks by providing a list of items to them, so that the parameters for a task will be provided by variables defined under Ansible with_items. For this we have a playbook like below where we are creating more than one file and set ownership, permission to it. For this we have a playbook like below, where we are using Ansible debug and file module to display registered values and creating files.

Code:

---
- hosts: all
tasks:
- name: checking the file's existance before creation
shell: "ls -l /tmp/sample*"
register: var_output
ignore_errors: yes
- name: here print the output
debug:
var: var_output.stdout_lines
- name: create file with different user ownership and permission
file:
path: "/tmp/{{ item.name }}"
state: touch
owner: "{{ item.username }}"
mode: "{{ item.permission }}"
with_items:
- { name: sample1, username: testuser, permission: '0644' }
- { name: sample2, username: test_user, permission: '0755' }
- name: checking the file's existance after creation
shell: "ls -l /tmp/sample*"
register: var_output_1
- name: here print the output
debug:
var: var_output_1.stdout_lines

Run this playbook like below:

ansible-playbook  ansible_with_items_creating_files.yaml

In the output we can see the how first these files named sample1 and sample2 were not existing and system gave error, then we created those files using Ansible file module and passed parameter values using with_items. Then on again checking we can see files are now there with required ownership and permission.

Output:

Conclusion

As we saw in this article, Ansible with_items is an important plugin which can help you to save a lot of efforts and enable you to use loops in playbooks, this is similar to using a for loop in scripting. You must have good practice over it so that complex playbook can be created where multiple variables are processed and returned.

This is a guide to Ansible with_items. Here we discuss the introduction, how does ansible with_item works along with sample code. You may also have a look at the following articles to learn more –

1. Ansible local_action
2. Ansible File Module
3. Ansible Playbooks
4. Ansible ad-hoc Commands