Updated May 20, 2023
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 these plugins provide is converted to a 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?
The ansible with_items plugin is widely used. 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, the task will be performed for all items in that list. If a high-level item also has 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 that needs 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 the local Ansible controller node, like any other plugin.
How does Ansible with_item work?
Ansible with_items is a keyword you will use in the playbook and provide a list of items under it. These are some scenarios when you have a simple list; a thing is a list is also a list, and each item in the list is a combination of a few variables.
Let us see how its syntax will look:
1. A simple list will be like the one below and used in the following task.
- 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 will look 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 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
Using examples, we will now see about the 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 used for testing. In the practice lab, we have an Ansible control server, “ansible-controller,” and two target machines named host-two and host-one.
We will create playbooks and run Ansible commands on the 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 types of lists to it and use Ansible debug module to check the output. For this purpose, we have a playbook like the one 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 the one below:
ansible-playbook ansible_with_items_lists.yaml
In the output, we can see how different lists are seen by the Ansible with_items plugin.
Output:
Example #2
In this example, we will do some tasks by providing them with a list of items so variables defined under Ansible with_items will supply the task parameters. For this, we have a playbook like the one below where we create multiple files and set ownership and permission to them. For this, we have a playbook like the one below, where we use Ansible debug and file module to display registered values and create 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 the one below:
ansible-playbook ansible_with_items_creating_files.yaml
In the output, we can see how, first, these files named sample1 and sample2 were not existing, and the system gave an error; then, we created those files using the Ansible file module and passed parameter values using with_items. Then on again checking, we can see files are now there with the required ownership and permission.
Output:
Conclusion
As we saw in this article, Ansible with_items is an essential plugin that can help you to save a lot of effort and enable you to use loops in playbooks; this is similar to using a for loop in scripting. You must practice it well to create a complex playbook where multiple variables are processed and returned.
Recommended Articles
This is a guide to Ansible with_items. Here we discuss the introduction, how ansible with_item works, along with sample code. You may also have a look at the following articles to learn more –
