Ansible get_url Module: Download Files from URL

When installing software, deploying apps, or updating systems using an Ansible playbook, you often need to download files from external sources. These files are usually available at a URL.

The get_url module lets you download files and save them to a specific location on your target system.

Learn how to use the get_url module to download files and automate tasks in your playbooks.

Prerequisites

• Access to the command line.
• Ansible installed.
• A reachable remote host.

How to Use Ansible get_url Module: Basic Example

This section shows how to use the get_url module in a playbook to download files to your managed nodes. The commands are demonstrated on Ubuntu 24.04, but they work on most Linux distributions.

Step 1: Create Project Directory

Ansible projects are usually organized in directories that store playbooks and other related files.

Create a directory for your project:

mkdir -p ~/myproject/ansible-get-url

Use the cd command to navigate to the directory:

cd ~/myproject/ansible-get-url

Now that you are in the project directory, you can create your inventory file and playbook.

Step 2: Define Inventory

Ansible keeps track of the systems it manages using an inventory file. Open a text editor, such as nano, and create a file named inventory.ini:

nano inventory.ini

Add the following content, but replace the IP addresses with the actual addresses of your remote hosts:

[servers]
192.168.1.10
192.168.1.11

Each IP represents one managed node.

The servers group you defined in the inventory file must be referenced in your playbook so Ansible knows where to run tasks.

Step 3: Create a Playbook with get_url

The playbook below uses the get_url module to download a software package to managed nodes. Specifically, it downloads the Prometheus Node Exporter, which can then be installed on multiple servers to monitor system metrics.

Open a text editor and create a YAML file named download-binary.yml. Then, add the following content:

---
- name: Download Node Exporter on managed nodes
  hosts: servers
  become: yes

  tasks:
    - name: Create download directory
      file:
        path: /tmp/downloads
        state: directory
        mode: "0755"

    - name: Download Node Exporter archive
      get_url:
        url: https://github.com/prometheus/node_exporter/releases/download/v1.10.2/node_exporter-1.10.2.linux-amd64.tar.gz
        dest: /tmp/downloads/node_exporter.tar.gz
        mode: "0644"

The get_url module in this playbook uses the following parameters:

Step 4: Run the Playbook

Use the following command to run the playbook with your inventory file:

ansible-playbook -i inventory.ini download-binary.yml

When you run the playbook, Ansible then:

1. Connects to each remote host in the servers group.

2. Checks if the /tmp/downloads directory exists and creates it if it does not.

3. Uses the get_url module to download the Node Exporter archive from the URL.

4. Saves the file on each system using the parameters you set.

Step 5: Verify the Download

To confirm the download was successful, log into one of your managed nodes and use the ls command to check the file:

ls -lh /tmp/downloads

At this point, the file is downloaded to each managed node. You can now extend this playbook by adding tasks to extract the archive and install Node Exporter.

How to Use Ansible get_url Module: Advanced Examples

Downloads sometimes fail due to network issues or corrupted files. To maintain consistency across remote nodes, you can create more advanced playbooks that run multiple tasks and give you greater control over how files are downloaded.

Use a Checksum to Verify the Download

Before downloading software from an external source, you should always check the file's integrity with a checksum. To do this, add the checksum parameter to your playbook:

- name: Download Node Exporter - verify checksum
  get_url:
    url: https://github.com/prometheus/node_exporter/releases/download/v1.10.2/node_exporter-1.10.2.linux-amd64.tar.gz
    dest: /tmp/downloads/node_exporter.tar.gz
    checksum: "sha256:vendor_checksum"
    mode: "0644"

Replace vendor_checksum with the actual checksum. Software vendors usually list checksums on their download pages or in a separate file next to the download link (such as .sha256 or .md5). SHA256 is more commonly used and recommended for better security.

Download File and Get Checksum From a URL

You do not need to manually copy checksums for each file. Check if the software provider offers a checksum file alongside the download. You can reference the checksum file's URL directly in the checksum parameter:

- name: Download Node Exporter - verify checksum from URL
  get_url:
    url: https://github.com/prometheus/node_exporter/releases/download/v1.10.2/node_exporter-1.10.2.linux-amd64.tar.gz
    dest: /tmp/downloads/node_exporter.tar.gz
    checksum: "sha256:https://example.com/node_exporter.sha256"
    mode: "0644"

With this setup, Ansible will automatically download the checksum file and also verify the integrity of the downloaded file.

Force File Download

Ansible does not download a file again if it already exists. You can change this default behavior using the force parameter:

• force: yes. Ansible always downloads and overwrites the file.
• force: no. Ansible only downloads the file if it does not exist.

- name: Always download the latest Node Exporter archive
  get_url:
    url: https://github.com/prometheus/node_exporter/releases/download/v1.10.2/node_exporter-1.10.2.linux-amd64.tar.gz
    dest: /tmp/downloads/node_exporter.tar.gz
    force: yes
    mode: "0644"

In this example, force is set to yes. This means Ansible downloads a new copy and overwrites any existing file with the same name.

Set Up Timeout When URL Does Not Respond

If a file download fails because of a slow network or temporary server issues, you can configure Ansible to retry the task. The following parameters control how long Ansible waits and how many times it retries:

In this example, Ansible waits up to 30 seconds for the download to complete. If it fails, it retries up to 3 times, waiting 5 seconds between each attempt:

- name: Download Node Exporter with retry logic
  get_url:
    url: https://github.com/prometheus/node_exporter/releases/download/v1.10.2/node_exporter-1.10.2.linux-amd64.tar.gz
    dest: /tmp/downloads/node_exporter.tar.gz
    timeout: 30
  register: download_result
  retries: 3
  delay: 5
  until: download_result is succeeded

The until condition tells Ansible to keep retrying the task until it succeeds or reaches the retry limit.

Download File from Protected URL (Basic Authentication)

Files in private repositories or on internal company servers often require basic authentication. This means you need to provide a username and password to access them. Use the url_username and url_password parameters to pass the required credentials:

- name: Download protected file
  get_url:
    url: https://somecompany.com/protected_files/file.tar.gz
    dest: /tmp/downloads/file.tar.gz
    url_username: your_username
    url_password: your_password
    mode: "0644"

Do not keep sensitive information, such as passwords, directly in your playbooks. In production environments, use tools like Ansible Vault to store credentials and reference them at runtime.

Complete Node Exporter Example

The following example brings together checksum verification, retries, timeouts, and forced downloads into one playbook:

- name: Download Node Exporter with reliability checks
  hosts: servers
  become: yes

  tasks:
    - name: Ensure download directory exists
      file:
        path: /tmp/downloads
        state: directory
        mode: "0755"

    - name: Download Node Exporter with checksum and retries
      get_url:
        url: https://github.com/prometheus/node_exporter/releases/download/v1.10.2/node_exporter-1.10.2.linux-amd64.tar.gz
        dest: /tmp/downloads/node_exporter.tar.gz
        checksum: "sha256:expected_checksum_value"
        timeout: 30
        force: yes
        mode: "0644"
      register: download_result
      retries: 3
      delay: 5
      until: download_result is succeeded

When you run this playbook, Ansible:

1. Creates the /tmp/downloads directory on each managed node.

2. Starts downloading the Node Exporter archive from the given URL.

3. Verifies the file with the provided SHA256 checksum to make sure it is not corrupted.

4. Waits up to 30 seconds for the server to respond before timing out.

5. Forces the download even if the file already exists on the system, to ensure the latest version is used.

6. Sets file permissions to 0644 so that all users can read the file, while only the owner can modify it.

7. Retries the download up to 3 times if it fails.

8. Waits 5 seconds between each retry attempt to avoid overwhelming the server.

9. Keeps retrying until the download works or all attempts have been used.

You can use this playbook as a starting point and update the URL, destination path, and any parameters to fit your setup and download requirements.

Conclusion

By following the steps in this guide, you can now use the get_url module to download files in real-world playbooks and configure parameters to verify files and handle errors.

As your playbooks become more complex, try combining get_url with the stat module to check if a file exists or inspect its properties before downloading it.