Updated April 14, 2023
Introduction to Ansible Fetch
Ansible fetch module is a file-based module, which is intended to work on files. This module is similar to Ansible copy module, but by default works in reverse order, in terms of source and destination. It is one of such modules that you might need on day to day basis while working on administrative or change management tasks on remote target machines. There are many other modules like a copy, template, etc. which works more or less in a similar way, there usability completely depends on the available feature parameters. In this article, we will learn about the Ansible Fetch module by using some examples and details on parameters that are usable under this module.
What is Ansible Fetch?
Ansible fetch module is used to fetch files from remote hosts and store them on the local Ansible controller machine in a file tree structure. This is a simple and easy to use the module. But one should know below points while working on the Ansible fetch module: –
- This module will treat remote machines as a source of files and local controller machines as a destination.
- Fetched files are organized by hostname, in a file tree structure.
- Files with different contents but the same name are overwritten on destination.
- This module works as it is, for Microsoft Windows machines as well.
- It is suggested to not use this module with Ansible to become parameters as this will lead to doubling the size of the transfer file. As checksum will also be calculating. This will then lead to consuming all available memory on remote or local hosts causing MemoryError.
- When reading of remote files is not possible, then we shall use fail_whenor ignore_errorsor fail_on_missing, to avoid failure of the playbook.
How Does Ansible Fetch Work?
To efficiently use Ansible fetch module, one much learn about all available parameters, their acceptable values. Also, there are some parameters that have default values set always, which will be realized to your playbook even if you do not mention the related parameter in the playbook. So these become more important to know. Below is a list of all available parameters and related acceptable or default values.
- dest: This is to set the directory where fetched files will be saved. Point to note that under this directory another directory will be created which is named after the hostname of target remote systems, but based of inventory entries. Under this directory, the whole directory structure as a source will be created and then file will be copied into it.
- fail_on_missing: Default is yes. This will cause the playbook failure when Ansible is unable to read files on source systems, reason can be anything like permission, non-existence, etc. Available values are yes and no.
- flat: Default is no. Acceptable values are yes and no. This is to set the override the default behavior of the fetch module. Thus to behave in such a way where files will be copied directly to destination location without creating hostname-based directory structure.
- src: To give the file name on remote systems to fetch. This must be a filename, not any directory name, as fetching of the directory is not supported yet.
- validate_checksum: Default is yes. Acceptable values are yes and no. To verify the source and destination checksum of files after fetching.
Examples to Implement Ansible Fetch
In this section, we will learn by doing looking at some examples where we tried to test the functionality of the Ansible reboot module. But we shall know about our lab environment first before moving ahead in this section.
Here we have one Ansible controller node named as ansible-controller. As target nodes, we have two remote machines. First machine is a Red Hat Enterprise Linux machine named as host-one and the second machine is an Ubuntu machine named as host-two. We will run our playbooks on the Ansible controller machine and make changes on remote target machines.
Example #1
In this example, we have a playbook that is used to fetch a file from remote target nodes and store on the local Ansible controller machine. Then we will check on the local Ansible controller machine that how the file is stored and what directory tree structure is created for this.
Code:
---
- hosts: all
tasks:
- name: here we are using Ansible fetch module to copy file from remote machines to local.
fetch:
src: /var/tmp/sample.txt
dest: /tmp/fetched
Then running this playbook like below:
# ansible-playbook ansible_fetch.yaml
Now in the output, we can see that files are fetched and stored on Ansible local machine in a directory structure.
Output:
Upon checking the directory structure, we found that a full directory structure has been created on the local machine.
Also, check the timestamp of files and directories.
As we saw in above, directories named fetched, <hostname> based (host-one and host-two), var and tmp were created. Then file is stored is under this. This is as per the default behavior of this module.
Example #2
In this example, we have a playbook that is used to fetch a file from remote target nodes and store on local Ansible controller machine. Here we have used a parameter named flat=yes. This is used to override the default behavior of the Ansible fetch module and copy file as it is with name and under path mentioned in the dest parameter. Then we will check on the local Ansible controller machine that how the file is stored and what directory tree structure is created for this.
Code:
---
- hosts: all
tasks:
- name: here we are using Ansible fetch module with some flat parameter
fetch:
src: /var/tmp/sample.txt
dest: /tmp/file-{{ ansible_hostname }}
flat: yes
Then running this playbook like below: –
# ansible-playbook ansible_fetch_flat.yaml -v
Output:
Then stored on Ansible local machine in the same directory with a new name and no new directory structure is created.
Conclusion
As we saw in this article, Ansible fetch module is easy to use though a very useful module, which you will definitely need in your Ansible skill set. Also having knowledge of its all available features and possibilities will enable you to use it to full extend. So learn it first and then use it.
Recommended Article
This is a guide to Ansible Fetch. Here we discuss What is Ansible Fetch and its syntax along with examples as well as code implementation. You can also go through our other suggested articles to learn more –
