Ansible - Lookups

“Lookup plugins retrieve data from outside sources such as files, databases, key/value stores, APIs, and other services.”

“Lookup plugins are an Ansible-specific extension to the Jinja2 templating language. You can use lookup plugins to access data from outside sources (files, databases, key/value stores, APIs, and other services) within your playbooks. Like all templating, lookups execute and are evaluated on the Ansible control machine. Ansible makes the data returned by a lookup plugin available using the standard templating system.”

• Official Document
• Big Index of All Lookups

Show a list of all lookups ( list plugins and filter for lookup ):

ansible-doc -t lookup -l

Example using lookups:

vars:
  motd_value: "{{ lookup('file', '/etc/motd') }}"
tasks:
  - debug:
      msg: "motd value is {{ motd_value }}"

Use lookups here:

• Playbook
• Variable file
• Jinja2 template

Functionality:

• Use “allow_unsafe=True” to allow Jinja2 templates to evaluate lookup values.
• lookups return string of comma separated values by default
• can use “wantlist=True” to return a list
• can also user query to call a lookup and return a list

Ways to use a lookup:

lookup(‘dict’, dict_variable, wantlist=True)	return a list
query(‘dict’, dict_variable)	return a list
q(‘dict’, dict_variable)	short form of query
with_dict:	for looping

File Lookup Examples

Read file as a string:

    - debug:
        msg: "{{ lookup('file', '/etc/hosts') }}"

Read each file as a string:

    - debug:
        msg: "TEST: {{ item }}"
      with_file:
        - '/etc/hosts'
        - '/etc/passwd'

Glob Lookup Examples

Glob files, return string with commas:

    - debug:
        msg: "{{ lookup('fileglob', '/etc/*') }}"

Glob files, return list:

    - debug:
        msg: "{{ lookup('fileglob', '/etc/*', wantlist=True) }}"

Glob files, return list:

    - debug:
        msg: "{{ query('fileglob', '/etc/*') }}"

Glob files, loop over each:

    - debug:
        msg: "TEST: {{ item }}"
      with_fileglob:
        - '/etc/*'

More Examples

Simple with_items:

tasks:
  - name: count to 3
    debug: msg={{ item }}
    with_items: [1, 2, 3]

More complicated example:

tasks:
  - name: 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']

Ignore errors or use warning instead of error:

- name: if this file does not exist, I do not care .. file plugin itself warns anyway ...
  debug: msg="{{ lookup('file', '/nosuchfile', errors='ignore') }}"

- name: if this file does not exist, let me know, but continue
  debug: msg="{{ lookup('file', '/nosuchfile', errors='warn') }}"

Larger Example

The dict lookup can convert a dictionary to a list containing smaller dictionaries ( key / value paires ) that can be iterated over.

---
- name: A Test Playbook
  hosts: all
  vars:
    dict1:
      OS: Ubuntu
      IP: 192.168.3.2
      CPU: intel
      Mem: 32
  tasks:

    - debug:
        var: "lookup('dict', dict1)"
    - debug:
        var: "lookup('dict', dict1, wantlist=True)"
    - debug:
        var: "query('dict', dict1)"
    - debug:
        var: "q('dict', dict1)"

    - debug:
        var: "{{ item }}"
      with_dict: "{{ dict1 }}"

    - debug:
        var: "{{ item }}"
      with_dict:
        a: "one"
        b: "two"