Ansible Unarchive Module with Practical Examples

The Unarchive module is part of Ansible’s core modules, making it a reliable choice for file extraction tasks. It supports various compression formats, including tar, gz, bz2, and zip. This module is useful when deploying applications or configuration files packaged in tarballs or zip files.

In this guide, we’ll explore the usage of the Unarchive module, using practical examples to help you understand its capabilities and applications.

Basic Syntax

The basic syntax of the Unarchive module is simple. Below is a breakdown of all the available parameters:

- name: Unarchive a file
  ansible.builtin.unarchive:
    src: /path/to/archive.tar.gz      
    dest: /path/to/destination/       
    remote_src: no                    
    creates: /path/to/created/file    
    list_files: no                    
    extra_opts:                       
      - "--strip-components=1"
    keep_newer: no                    
    mode: '0644'

Here’s a short explanation of each part of the provided playbook:

• name: Unarchive a file: Defines the name of the task, which is to unarchive a file.
• ansible.builtin.unarchive: Uses the unarchive module to extract an archive.
• src: Specifies the local source file path (/path/to/archive.tar.gz).
• dest: Defines the destination directory (/path/to/destination/) where the archive will be extracted.
• remote_src: Set to no, meaning the source file is on the local machine, not remote.
• creates: Specifies a file that will be checked; if it exists, the extraction is skipped.
• list_files: Set to no, meaning it will not list the files in the archive before extraction.
• extra_opts: Provides extra options for extraction (–strip-components=1 removes one leading directory from the extracted files).
• keep_newer: Set to no, meaning existing files in the destination will be overwritten.
• mode: Sets the permissions of the extracted files to ‘0644’.

Unarchive a File to a Specific Directory

To unarchive a file to a specific directory on a remote host, you can use the following playbook:

---
- name: Unarchive file example
  hosts: webservers
  tasks:
    - name: Unarchive the tar.gz file
      ansible.builtin.unarchive:
        src: /tmp/my_archive.tar.gz
        dest: /var/www/html/

In this example playbook, the my_archive.tar.gz file located in the /tmp directory is uncompressed into the /var/www/html/ directory on the remote host.

Unarchive a File from a Remote URL

The Unarchive module also supports downloading and uncompressing files from remote URLs. This is useful for fetching files directly from the internet and deploying them on your servers.

---
- name: Unarchive from remote URL example
  hosts: webservers
  tasks:
    - name: Download and unarchive file from URL
      ansible.builtin.unarchive:
        src: https://example.com/files/my_archive.tar.gz
        dest: /var/www/html/
        remote_src: yes

In this example, the my_archive.tar.gz file is downloaded from the specified URL and uncompressed into the /var/www/html/ directory on the remote host.

Unarchive with Remote Source and Destination

If both the source and destination are remote, set remote_src to yes:

---
- name: Unarchive remote source to remote destination
  hosts: webservers
  tasks:
    - name: Unarchive the file from remote source
      ansible.builtin.unarchive:
        src: /remote/path/to/archive.zip
        dest: /var/www/html/
        remote_src: yes

This playbook extracts the contents of the archive located at /remote/path/to/archive.zip on the remote machine itself (indicated by remote_src: yes) into the /var/www/html/ directory on the same machine. This is useful for deploying files or applications directly to the web server.

Handling Permissions

You may need to adjust file permissions after unarchiving. This can be done using the mode parameter or by adding a separate task with a file module to change permissions:

---
- name: Unarchive and set permissions
  hosts: webservers
  tasks:
    - name: Unarchive the file
      ansible.builtin.unarchive:
        src: /tmp/my_archive.tar.gz
        dest: /var/www/html/
        mode: '0755'
    - name: Set permissions
      ansible.builtin.file:
        path: /var/www/html/
        state: directory
        mode: '0755'

This playbook unarchives a file to /var/www/html/ on remote web servers, setting extracted files’ permissions to 0755 and ensuring the destination directory has the same permissions.

Creating Idempotent Playbooks

Ansible modules are idempotent by nature, meaning they ensure the desired state without repeating actions if the state is already achieved.

---
- name: Idempotent unarchive example
  hosts: webservers
  tasks:
    - name: Check if the file exists
      ansible.builtin.stat:
        path: /var/www/html/index.html
      register: stat_result

    - name: Unarchive only if necessary
      ansible.builtin.unarchive:
        src: /tmp/my_archive.tar.gz
        dest: /var/www/html/
      when: not stat_result.stat.exists

This playbook checks if /var/www/html/index.html exists and only unarchives /tmp/my_archive.tar.gz to /var/www/html/ if the file does not already exist.

Conclusion

The Ansible Unarchive module is a versatile tool for uncompressing files and directories on remote hosts. Whether you’re deploying web applications, configuration files, or any other packaged content, this module simplifies the process and ensures consistency across your infrastructure. You can also use the archive module to compress files remotely.

FAQs