first_found – return first file found from list

first_found – return first file found from list

• Synopsis
• Parameters
• Notes
• Examples
• Return Values
• Status

Synopsis

• this lookup checks a list of files and paths and returns the full path to the first combination found.
• As all lookups, when fed relative paths it will try use the current task’s location first and go up the chain to the containing role/play/include/etc’s location.
• The list of files has precedence over the paths searched. i.e, A task in a role has a ‘file1’ in the play’s relative path, this will be used, ‘file2’ in role’s relative path will not.
• Either a list of files _terms or a key files with a list of files is required for this plugin to operate.

Parameters

Parameter	Choices/Defaults	Configuration	Comments
_terms -			list of file names
files -			list of file names
paths -			list of paths in which to look for the files
skip boolean	Default: "no"		Return an empty list if no file is found, instead of an error.

Notes

Note

• This lookup can be used in ‘dual mode’, either passing a list of file names or a dictionary that has files and paths.

Examples

- name: show first existing file or ignore if none do
  debug: msg={{lookup('first_found', findme, errors='ignore')}}
  vars:
    findme:
      - "/path/to/foo.txt"
      - "bar.txt"  # will be looked in files/ dir relative to role and/or play
      - "/path/to/biz.txt"

- name: |
        copy first existing file found to /some/file,
        looking in relative directories from where the task is defined and
        including any play objects that contain it
  copy: src={{lookup('first_found', findme)}} dest=/some/file
  vars:
    findme:
      - foo
      - "{{inventory_hostname}}"
      - bar

- name: same copy but specific paths
  copy: src={{lookup('first_found', params)}} dest=/some/file
  vars:
    params:
      files:
        - foo
        - "{{inventory_hostname}}"
        - bar
      paths:
        - /tmp/production
        - /tmp/staging

- name: INTERFACES | Create Ansible header for /etc/network/interfaces
  template:
    src: "{{ lookup('first_found', findme)}}"
    dest: "/etc/foo.conf"
  vars:
    findme:
      - "{{ ansible_virtualization_type }}_foo.conf"
      - "default_foo.conf"

- name: read vars from first file found, use 'vars/' relative subdir
  include_vars: "{{lookup('first_found', params)}}"
  vars:
    params:
      files:
        - '{{ansible_os_distribution}}.yml'
        - '{{ansible_os_family}}.yml'
        - default.yml
      paths:
        - 'vars'

Return Values

Common return values are documented here, the following are the fields unique to this lookup:

Key	Returned	Description
_raw -		path to file found

Status

• This lookup is not guaranteed to have a backwards compatible interface. [preview]
• This lookup is maintained by the Ansible Community. [community]

Authors

• Seth Vidal <[email protected]>

Hint

If you notice any issues in this documentation, you can edit this document to improve it.

Hint

Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up.

© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.8/plugins/lookup/first_found.html