diff --git a/lib/ansible/plugins/lookup/first_found.py b/lib/ansible/plugins/lookup/first_found.py index 0b066b2507..2798a0d286 100644 --- a/lib/ansible/plugins/lookup/first_found.py +++ b/lib/ansible/plugins/lookup/first_found.py @@ -11,6 +11,10 @@ DOCUMENTATION = """ short_description: return first file found from list description: - 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. options: _terms: description: list of file names @@ -20,38 +24,52 @@ DOCUMENTATION = """ """ EXAMPLES = """ -- name: show first existin file - debug: var=item - with_first_found: - - "/path/to/foo.txt" - - "bar.txt" # will be looked in files/ dir relative to play or in role - - "/path/to/biz.txt" +- name: show first existing file + debug: msg={{lookup('first_found', findme)}} + 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 - copy: src={{item}} dest=/some/file - with_first_found: - - foo - - "{{inventory_hostname}} - - bar +- 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={{item}} dest=/some/file - with_first_found: - - files: - - foo - - "{{inventory_hostname}} - - bar - paths: - - /tmp/production - - /tmp/staging + copy: src={{lookup('first_found', findme, mypaths}} dest=/some/file + vars: + findme: + - foo + - "{{inventory_hostname}} + - bar + mypaths: + - /tmp/production + - /tmp/staging - name: INTERFACES | Create Ansible header for /etc/network/interfaces template: - src: "{{ item }}" + src: "{{ lookup('first_found', findme)}}" dest: "/etc/foo.conf" - with_first_found: - - "{{ ansible_virtualization_type }}_foo.conf" - - "default_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', findme, paths=['vars'])}}" + vars: + findme: + - '{{ansible_os_distribution}}.yml' + - '{{ansible_os_family}}.yml' + - default.yml """ RETURN = """