ansible.builtin.first_found – return first file found from list¶
Note
This module is part of ansible-base
and included in all Ansible
installations. In most cases, you can use the short module name
first_found even without specifying the collections:
keyword.
Despite that, we recommend you use the FQCN for easy linking to the module
documentation and to avoid conflicting with other collections that may have
the same module name.
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¶
Notes¶
Note
This lookup can be used in ‘dual mode’, either passing a list of file names or a dictionary that has
files
andpaths
.
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: |
include tasks only if files exist. Note the use of query() to return
a blank list for the loop if no files are found.
import_tasks: '{{ item }}'
vars:
params:
files:
- path/tasks.yaml
- path/other_tasks.yaml
loop: "{{ query('first_found', params, errors='ignore') }}"
- 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_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
list
/ elements=path
|
success |
path to file found
|
Authors¶
Seth Vidal (!UNKNOWN) <skvidal@fedoraproject.org>