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.
_terms
or a key files
with a list of files is required for this plugin to operate.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. |
Note
files
and paths
.- 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'
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 |
© 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