Ansible lookup file Plugin: Read Local File Content into Variable (Guide)

How to read a file into a variable on the host with Ansible?

I'm going to show you a live Playbook with some simple Ansible code. I'm Luca Berton and welcome to today's episode of Ansible Pilot.

See also: Ansible Read JSON File: lookup file Plugin & from_json (Guide)

Ansible read a file into a variable

• ansible.builtin.file • read file contents

Let's deep dive into the Ansible lookup plugin file. Plugins are a way to expand the Ansible functionality. With lookup plugins specifically, you can load variables or templates with information from external sources. The full name is ansible.builtin.file, it's part of ansible-core and is included in all Ansible installations. The purpose of the file lookup plugin is to read file contents.

Parameters and Return Values

Parameters

• \_terms string - path(s) of files to read

Return Values

• \_raw list - content of file(s)

The parameters of the lookup plugin file. The only required parameter is the default "\_terms", with the path(s) of files to read. The normal usage is to assign the lookup plugin to a variable name that you could use in your playbook.

## Playbook

Read a file into a variable on the host with Ansible Playbook.

code

---
- name: read file on host
  hosts: all
  vars:
   contents: "{{ lookup('file','example.txt') }}"
  tasks:
   - name: print file
     ansible.builtin.debug:
      msg: "the content of file is {{ contents }}"

execution

ansible-pilot $ ansible-playbook -i virtualmachines/demo/inventory variables/read-file.yml
PLAY [read file on host] **************************************************************************
TASK [Gathering Facts] ****************************************************************************
ok: [demo.example.com]
TASK [print file] *********************************************************************************
ok: [demo.example.com] => {
    "msg": "the content of file is example contents"
}
PLAY RECAP ****************************************************************************************
demo.example.com           : ok=2    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0
ansible-pilot $

idempotency

ansible-pilot $ ansible-playbook -i virtualmachines/demo/inventory variables/read-file.yml
PLAY [read file on host] **************************************************************************
TASK [Gathering Facts] ****************************************************************************
ok: [demo.example.com]
TASK [print file] *********************************************************************************
ok: [demo.example.com] => {
    "msg": "the content of file is example contents"
}
PLAY RECAP ****************************************************************************************
demo.example.com           : ok=2    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0
ansible-pilot $

code with ❤️ in GitHub

See also: Creating a Custom Ansible Lookup Plugin in Python for Reading a File

Conclusion

Now you know how to read a file into a variable on host with Ansible.

File Lookup Examples

Read SSH key

- name: Deploy SSH key
  vars:
    ssh_key: "{{ lookup('file', '~/.ssh/id_rsa.pub') }}"
  ansible.posix.authorized_key:
    user: deploy
    key: "{{ ssh_key }}"

Read relative to playbook

- vars:
    config: "{{ lookup('file', playbook_dir + '/files/config.txt') }}"
  debug:
    msg: "{{ config }}"

Read and parse JSON

- set_fact:
    app_config: "{{ lookup('file', 'files/config.json') | from_json }}"
- debug:
    msg: "DB host: {{ app_config.database.host }}"

See also: Creating a Custom Ansible Lookup Plugin in Python for retrieving API token

file vs slurp vs fetch

| Method | Reads From | Returns | |--------|-----------|---------| | lookup('file') | Controller | String | | slurp module | Remote host | Base64 | | fetch module | Remote host | Downloads file |

Read from remote host

- name: Read remote file
  ansible.builtin.slurp:
    src: /etc/hostname
  register: remote_file
- debug:
    msg: "{{ remote_file.content | b64decode }}"

Use Cases

Deploy authorized keys from files

- ansible.posix.authorized_key:
    user: "{{ item.user }}"
    key: "{{ lookup('file', item.keyfile) }}"
  loop:
    - { user: alice, keyfile: files/alice.pub }
    - { user: bob, keyfile: files/bob.pub }

Conditional on file content

- set_fact:
    version: "{{ lookup('file', 'VERSION') | trim }}"
- include_tasks: upgrade.yml
  when: version is version('2.0', '<')

FAQ

What if the file doesn't exist?

Use errors='ignore':

msg: "{{ lookup('file', 'optional.txt', errors='ignore') | default('') }}"

Does file lookup work in templates?

Yes - {{ lookup('file', ...) }} reads from the controller filesystem in templates too.

Can I read binary files?

The file lookup is for text. Encode binary files to base64 first.

Related Articles

• rendering Jinja2 templates with Ansible • Ansible Inventory Guide • idempotent file ops with ansible.builtin.file