Ansible Fetch Module: Explained with Examples

The fetch module in Ansible is used to transsfer files from remote hosts to the local machine running the playbook. This is the reverse operation of the copy module, which transfers files from local to remote hosts. It is useful when automating workflows that involve retrieving logs, configuration files, or backups from multiple servers. By leveraging this module, you can easily set up tasks to gather critical files for later examination or archival.

Use cases include:

• Collecting log files for centralized analysis.
• Backing up configuration files before applying updates or changes.
• Gathering output from remote systems for compliance audits or reports.

This article will explain how to copy files from remote hosts using the Ansible fetch module.

Basic Syntax

The fetch module provides several parameters to control its behavior. Here is the basic syntax:

- name: Fetch file from remote host
  ansible.builtin.fetch:
    src: remote_path
    dest: local_path
    flat: yes/no

Explanation:

• src: The path to file on the remote host. This represents the source file that you want to retrieve.
• dest: The destination path on the control node where the file will be stored.
• flat: If true, the fetched file will not maintain its directory structure. If no, the file will retain the directory structure relative to the remote host. By default, flat is set to no.

Example 1: Fetch a Single File

This example illustrates how to fetch a specific log file from a remote server and save it in a local machine.

- name: Fetch a log file from the remote server
  hosts: all
  tasks:
    - name: Fetch the application log
      ansible.builtin.fetch:
        src: /var/log/app.log
        dest: /tmp/fetched_logs/
        flat: yes

This playbook fetches a specific file, app.log, from all remote servers defined in the inventory file and saves it locally to /tmp/fetched_logs/. The flat: yes option appends the hostname of the remote server to the fetched file’s name to prevent overwriting files from multiple servers.

Example 2: Fetch Files into a Specific Local Directory

In this scenario, you fetch a configuration file and maintain the directory structure of the remote host.

- name: Fetch configuration file
  hosts: all
  tasks:
    - name: Fetch nginx.conf to local directory
      ansible.builtin.fetch:
        src: /etc/nginx/nginx.conf
        dest: /backup/remote_configs/
        flat: no

In this playbook, flat: no ensures that the directory structure /etc/nginx/ is recreated under /backup/remote_configs/remote_hostname/.

Example 3: Fetch Files with Overwrite Protection

Sometimes, you may want to avoid overwriting existing files. You can register the task output and check whether a file was modified or rely on a checksum to verify file integrity.

- name: Fetch a file without overwriting
  hosts: all
  tasks:
    - name: Fetch the system log
      ansible.builtin.fetch:
        src: /var/log/syslog
        dest: /tmp/fetched_logs/
        flat: yes
      register: fetch_result

    - name: Debug fetch result
      debug:
        msg: "{{ fetch_result }}"

This playbook fetches the /var/log/syslog file from all remote servers to /tmp/fetched_logs/ on the control node without overwriting files, appending the hostname to each file, and uses the debug module to display the fetch result for verification.

Example 4: Fetch Multiple Files Dynamically

This example fetching multiple files matching a specific pattern from a remote machine.

- name: Fetch multiple log files
  hosts: all
  tasks:
    - name: Find log files
      ansible.builtin.find:
        paths: /var/log
        patterns: "*.log"
      register: log_files

    - name: Fetch all log files
      ansible.builtin.fetch:
        src: "{{ item.path }}"
        dest: /tmp/logs/
        flat: yes
      loop: "{{ log_files.files }}"

This playbook uses the find module to locate all .log files in the /var/log on remote servers, then iterates over the results using a loop for fetching each log file to /tmp/logs/ on the control node without overwriting.

Conclusion

The Ansible fetch module simplifies retrieving files from remote servers. It helps you gather logs, configuration files, and other data easily. Whether you need a single file or multiple matches, the fetch module’s flexibility allows you to handle various cases.  You can now manage file transfers across multiple hosts.

You can also combine the fetch module with modules like find or shell for dynamic file identification and retrieval.

FAQs

1. Do I need special permissions to use the Fetch module?

Yes, you need read permissions on the remote files you wish to fetch.

2. What happens if the remote file doesn’t exist?

The task will fail unless error handling, such as ignore_errors: yes, is specified.

3. What happens if the dest directory doesn’t exist?

Ansible will attempt to create the destination directory before saving the fetched file.