ansible.builtin.file lookup – read file contents

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 file 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 returns the contents from a file on the Ansible controller’s file system.

Terms

Parameter

Comments

Terms

string / required

path(s) of files to read

Keyword parameters

This describes keyword parameters of the lookup. These are the values key1=value1, key2=value2 and so on in the following examples: lookup('ansible.builtin.file', key1=value1, key2=value2, ...) and query('ansible.builtin.file', key1=value1, key2=value2, ...)

Parameter

Comments

lstrip

boolean

whether or not to remove whitespace from the beginning of the looked-up file

Choices:

  • false ← (default)

  • true

rstrip

boolean

whether or not to remove whitespace from the ending of the looked-up file

Choices:

  • false

  • true ← (default)

Notes

Note

  • When keyword and positional parameters are used together, positional parameters must be listed before keyword parameters: lookup('ansible.builtin.file', term1, term2, key1=value1, key2=value2) and query('ansible.builtin.file', term1, term2, key1=value1, key2=value2)

  • if read in variable context, the file can be interpreted as YAML if the content is valid to the parser.

  • this lookup does not understand ‘globbing’, use the fileglob lookup instead.

Examples

- ansible.builtin.debug:
    msg: "the value of foo.txt is {{lookup('ansible.builtin.file', '/etc/foo.txt') }}"

- name: display multiple file contents
  ansible.builtin.debug: var=item
  with_file:
    - "/path/to/foo.txt"
    - "bar.txt"  # will be looked in files/ dir relative to play or in role
    - "/path/to/biz.txt"

Return Value

Key

Description

Return value

list / elements=string

content of file(s)

Returned: success

Authors

  • Daniel Hokka Zakrisson

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.