Lookup plugins allow Ansible to access data from outside sources. This can include reading the filesystem in addition to contacting external datastores and services. Like all templating, these plugins are evaluated on the Ansible control machine, not on the target/remote.
The data returned by a lookup plugin is made available using the standard templating system in Ansible, and are typically used to load variables or templates with information from those systems.
Lookups are an Ansible-specific extension to the Jinja2 templating language.
Note
Warning
You can activate a custom lookup by either dropping it into a lookup_plugins directory adjacent to your play, inside a role, or by putting it in one of the lookup directory sources configured in ansible.cfg.
Lookup plugins can be used anywhere you can use templating in Ansible: in a play, in variables file, or in a Jinja2 template for the template module.
vars:
file_contents: "{{lookup('file', 'path/to/file.txt')}}"
Lookups are an integral part of loops. Wherever you see with_, the part after the underscore is the name of a lookup.
This is also the reason most lookups output lists and take lists as input; for example, with_items uses the items lookup:
tasks:
- name: count to 3
debug: msg={{item}}
with_items: [1, 2, 3]
You can combine lookups with ../playbooks_filters, ../playbooks_tests and even each other to do some complex data generation and maniplulation. For example:
tasks:
- name: valid but useless and over complicated chained lookups and filters
debug: msg="find the answer here:\n{{ lookup('url', 'http://google.com/search/?q=' + item|urlencode)|join(' ') }}"
with_nested:
- "{{lookup('consul_kv', 'bcs/' + lookup('file', '/the/question') + ', host=localhost, port=2000')|shuffle}}"
- "{{lookup('sequence', 'end=42 start=2 step=2')|map('log', 4)|list)}}"
- ['a', 'c', 'd', 'c']
You can use ansible-doc -t lookup -l to see the list of available plugins. Use ansible-doc -t lookup <plugin name> to see specific documents and examples.
See also