Updated April 6, 2023
Introduction to Ansible Lookup
In Ansible, we have advanced features like lookup plugins, which are Ansible specific extension to the Jinja2 templating language. Using lookup plugins we can evaluate data on the Ansible Control machine. This data is evaluated by plugins locally. But interesting is the fact that the source of this data can be external datastores or services. This feature makes lookup plugins powerful and useful.
There is a big list of available plugins including file, vars, password, URL, and many more, which we can use as per our environment, we will explore some of those in this document.
What is Ansible Lookup?
In Ansible, using lookup plugins, we can fetch data from external resources. These sources can be local filesystems or some external datastores or services. The data obtained by those sources is then evaluated by plugins and returned using Ansible templating systems and made available in that format.
Ansible Lookup plugin is mostly used for loading variables/templates containing information of or from external systems.
We must note below points while working with Ansible lookup plugins: –
- Lookups are executed with a working directory relative to the play or role, which is different from local tasks which work with working directory related to the executed
- This is an advance feature so you must have good knowledge of Ansible, it’s way to working and documentation source before using lookup plugins in
- All the processing on data is done locally so we must know that data after processing or evaluating must pass into a variable or use as a source of
- Custom plugins can be made activated by one of the following ways: –
- Putting it in lookup_plugins directory adjacent to
- Putting it in lookup_plugins directory inside a
- Putting in one of lookup directories sources configured in cfg
- We can combine Ansible plugins with filter and tests to manipulate the data or generate more data.
- From Ansible v2.5, we have a new jinja2 function was added for invoking lookup plugins, which is named as query, the main difference between both is that the return values of the query are always a list while lookup returns comma-separated values (CSV). We can use wantlist=True explicitly with a lookup to make it return a
How Does Ansible Lookup Works?
Ansible has a list of available default lookup plugins which can be used. Along with these we one can also create custom plugins to make use with lookup. The available list of lookup plugins may vary from Ansible version to version.
To get list of available lists of lookup plugins, you can use below command: –
ansible-doc -t lookup -l
This will output something like below, from this list you can choose a lookup plugin and as we said this list depends on the Ansible Version you have.
After choosing a lookup plugin, we must read its documentation and check possible examples by using below command:
ansible-doc -t lookup <plugin name>
Like we use below, where we are checking Ansible lookup plugin dig.
ansible-doc -t lookup dig
Output:
Though you can have different requirement of plugins in your environment, we would like to list few common and mostly used plugins below, just to add to our knowledge, so that you can make use of same if needed: –
- Config: This is to lookup the current values from the Ansible Configuration
- csvfile: This is used to use data from a CSV
- dict: This plugin is used to return values in key-value
- dig: This is used to query DNS by using a library named
- env: This is used to read the values of env.
- file: This is used to read the contents of a
- mini: This plugin is to read contents from an ini
- inventory_hostnames: To return the list of matching pattern
- Items: To return the item’s list
- lines: To read a line from the command
- list: To return the same output which is given as
- password: To generate or retrieve a random
- template: To return contents of a file after using jinja2 to template
- url: This is used to get specific content from a
- vars: This is to lookup the variables which are either templated or declared in Play
Examples to Implement Ansible Lookup
Now by using examples, we will try to learn about some of Ansible lookup plugins, which you might have to use in day to day operations. We will take some real-time examples, but before going there, we first understand our lab, we used for testing purpose.
- Here we have an Ansible control server named ansible-controller and two remotes hosts named host- one and host-two. We will create playbooks and run Ansible commands on the ansible-controller node and see the results on remote hosts.
- We will try to explore some of the Ansible Lookup Plugins by example. The use in these examples is completely to show you how to use these, your real-life use may be different from these.
Example #1
In this example, we will take contents from a local file on the Ansible control machine and display its output using Ansible lookup plugin For this we create a playbook, like below:
Code:
hosts:
localhost
tasks:
name: here we will display contents of
/tmp/samplefile debug:
msg: These are the contents of /tmp/samplefile -
{{lookup('file', '/tmp/samplefile')}}
We get output like below:
ansible-playbook ansible_lookup_file.yaml
Output:
Example #2
In this example, we will make a variable using lookup plugin vars. We will attempt to print hostnames of remote machines, for this, we create a playbook like below:
Code:
hosts:
all vars:
myvar:
ostname tasks:
name: Show value of 'variablename'
debug:
msg: "{{ lookup('vars', 'ansible_h' + myvar)}}"
On executing we get an output like below:
ansible-playbook ansible_lookup_vars1.yaml
Output:
Conclusion
As we saw that Ansible have lookup plugins which have usability in variety across many technologies. But we must take care of the syntax very well to get the desired result. Also, the documentation for each lookup plugin must be referred before using a plugin, as each plugin works differently. So learn it first then use it.
Recommended Articles
This is a guide to Ansible Lookup. Here we discuss an introduction to Ansible Lookup, syntax, how does lookup work with examples to implement. You can also go through our other related articles to learn more –
