ansible.builtin.first_found – return first file found from list
Note
This lookup plugin is part of ansible-core
and included in all Ansible installations. In most cases, you can use the short plugin name first_found
even without specifying the collections:
keyword. However, we recommend you use the FQCN for easy linking to the plugin documentation and to avoid conflicting with other collections that may have the same lookup plugin 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 locations of role / play / include and so on.
- The list of files has precedence over the paths searched. For example, 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 keyfiles
with a list of files is required for this plugin to operate.
Parameters
Parameter | Choices/Defaults | Configuration | Comments |
---|---|---|---|
_terms string | A list of file names. | ||
files list / elements=string | Default: [] | A list of file names. | |
paths list / elements=string | Default: [] | A list of paths in which to look for the files. | |
skip boolean |
| 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
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. include_tasks: file: "{{ query('first_found', params) }}" vars: params: files: - path/tasks.yaml - path/other_tasks.yaml - 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>
© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/ansible/builtin/first_found_lookup.html