Lookup Plugins

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

• Lookups are executed with a working directory relative to the role or play,as opposed to local tasks, which are executed relative the executed script.
• Since Ansible version 1.9, you can pass wantlist=True to lookups to use in Jinja2 template “for” loops.
• Lookup plugins are an advanced feature; to best leverage them you should have a good working knowledge of how to use Ansible plays.

Warning

• Some lookups pass arguments to a shell. When using variables from a remote/untrusted source, use the |quote filter to ensure safe usage.

Enabling Lookup Plugins

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.

Using Lookup Plugins

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 Filters, Tests and even each other to do some complex data generation and manipulation. For example:

tasks:
  - name: valid but useless and over complicated chained lookups and filters
    debug: msg="find the answer here:\n{{ lookup('url', 'https://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']

New in version 2.6.

You can now control how errors behave in all lookup plugins by setting errors to ignore, warn, or strict. The default setting is strict, which causes the task to fail. For example:

To ignore errors:

- name: file doesnt exist, but i dont care .. file plugin itself warns anyways ...
  debug: msg="{{ lookup('file', '/idontexist', errors='ignore') }}"

[WARNING]: Unable to find '/idontexist' in expected paths (use -vvvvv to see paths)
 
ok: [localhost] => {
    "msg": ""
}

To get a warning instead of a failure:

- name: file doesnt exist, let me know, but continue
  debug: msg="{{ lookup('file', '/idontexist', errors='warn') }}"

[WARNING]: Unable to find '/idontexist' in expected paths (use -vvvvv to see paths)
 
[WARNING]: An unhandled exception occurred while running the lookup plugin 'file'. Error was a <class 'ansible.errors.AnsibleError'>, original message: could not locate file in lookup: /idontexist
 
ok: [localhost] => {
    "msg": ""
}

Fatal error (the default):

- name: file doesnt exist, FAIL (this is the default)
  debug: msg="{{ lookup('file', '/idontexist', errors='strict') }}"

[WARNING]: Unable to find '/idontexist' in expected paths (use -vvvvv to see paths)
 
fatal: [localhost]: FAILED! => {"msg": "An unhandled exception occurred while running the lookup plugin 'file'. Error was a <class 'ansible.errors.AnsibleError'>, original message: could not locate file in lookup: /idontexist"}

query

New in version 2.5.

In Ansible 2.5, a new jinja2 function called query was added for invoking lookup plugins. The difference between lookup and query is largely that query will always return a list.The default behavior of lookup is to return a string of comma separated values. lookup can be explicitly configured to return a list using wantlist=True.

This was done primarily to provide an easier and more consistent interface for interacting with the new loop keyword, while maintaining backwards compatibiltiy with other uses of lookup.

The following examples are equivalent:

lookup('dict', dict_variable, wantlist=True)
 
query('dict', dict_variable)

As demonstrated above the behavior of wantlist=True is implicit when using query.

Additionally, q was introduced as a shortform of query:

q('dict', dict_variable)

Plugin List

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.

• aws_account_attribute – Look up AWS account attributes.
• aws_service_ip_ranges – Look up the IP ranges for services provided in AWS such as EC2 and S3.
• aws_ssm – Get the value for a SSM parameter or all parameters under a path.
• cartesian – returns the cartesian product of lists
• chef_databag – fetches data from a Chef Databag
• config – Lookup current Ansible configuration values
• conjur_variable – Fetch credentials from CyberArk Conjur.
• consul_kv – Fetch metadata from a Consul key value store.
• cpm_metering – Get Power and Current data from WTI OOB/Combo and PDU devices
• cpm_status – Get status and parameters from WTI OOB and PDU devices.
• credstash – retrieve secrets from Credstash on AWS
• csvfile – read data from a TSV or CSV file
• cyberarkpassword – get secrets from CyberArk AIM
• dict – returns key/value pair items from dictionaries
• dig – query DNS using the dnspython library
• dnstxt – query a domain(s)’s DNS txt fields
• env – read the value of environment variables
• etcd – get info from an etcd server
• file – read file contents
• fileglob – list files matching a pattern
• filetree – recursively match all files in a directory tree
• first_found – return first file found from list
• flattened – return single list completely flattened
• grafana_dashboard – list or search grafana dashboards
• hashi_vault – retrieve secrets from HashiCorp’s vault
• hiera – get info from hiera data
• indexed_items – rewrites lists to return ‘indexed items’
• ini – read data from a ini file
• inventory_hostnames – list of inventory hosts matching a host pattern
• items – list of items
• k8s – Query the K8s API
• keyring – grab secrets from the OS keyring
• lastpass – fetch data from lastpass
• lines – read lines from command
• list – simply returns what it is given.
• mongodb – lookup info from MongoDB
• nested – composes a list with nested elements of other lists
• nios – Query Infoblox NIOS objects
• nios_next_ip – Return the next available IP address for a network
• nios_next_network – Return the next available network range for a network-container
• onepassword – fetch field values from 1Password
• onepassword_raw – fetch raw json data from 1Password
• password – retrieve or generate a random password, stored in a file
• passwordstore – manage passwords with passwordstore.org’s pass utility
• pipe – read output from a command
• random_choice – return random element from list
• redis – fetch data from Redis
• redis_kv – fetch data from Redis
• sequence – generate a list based on a number sequence
• shelvefile – read keys from Python shelve file
• subelements – traverse nested key from a list of dictionaries
• template – retrieve contents of file after templating with Jinja2
• together – merges lists into synchronized list
• url – return contents from URL
• vars – Lookup templated value of variables

See also

• About Playbooks
• An introduction to playbooks
• Inventory Plugins
• Ansible inventory plugins
• Callback Plugins
• Ansible callback plugins
• Filters
• Jinja2 filter plugins
• Tests
• Jinja2 test plugins
• Lookups
• Jinja2 lookup plugins
• User Mailing List
• Have a question? Stop by the google group!
• irc.freenode.net

• ansible IRC chat channel