One area that Ansible’s efficiency makes a huge difference is in the handling of file transfer from the local machine to remote hosts. A task that’s undertaken by the Ansible copy module.

This blog explores how the Ansible copy module works, its syntax, and some practical use cases.

Ansible Copy

The Ansible Copy module allows users to copy files and directories from the control system to remote hosts. It offers an effective approach to managing file transfers in a way that guarantees target hosts' configuration consistency. It has options for controlling how the copy operation behaves, such as making backup copies of files, only copying files if the source has changed, and recursively copying directories.

Ansible Copy Module Syntax

To utilize the capabilities of the Ansible copy module, you must first understand its fundamental usage, including the syntax and arguments involved. The basic syntax of the copy module is as follows:

tasks: 
- name: Copy file or template
  copy:
    src: <source_file_or_template>
    dest: <destination_file>

Here, <source_file_or_template> is the path to the file that you want to copy, and <destination_file> represents the path on the target host where the file should be copied.

Copying Files from Local to Remote

Let’s consider a simple example where we want to copy a file from the control machine to a remote host. Suppose we have a file named file.txt located at /home/ubuntu/local/file.txt on the control machine, and we want to copy it to the directory /home/ubuntu/remote/ on the remote host. Below is the code for the task to copy file.txt from the local system to the remote system.

tasks: 
- name: Copy file to remote host
  copy:
    src: /home/ubuntu/local/file.txt
    dest: /home/ubuntu/remote/file.txt

In this example, the src parameter specifies the source file path on the control host, and the dest parameter defines the destination file path on the remote host. When you perform this task, Ansible connects to the remote host, transfers file.txt from the control host to the destination host, and drops it at the mentioned destination.

Copying Directories from Local to Remote

The copy module also supports the copying of entire directories. To copy a directory from a control machine to a remote host, you must set the remote_src parameter in the task to yes.

tasks:  
- name: Copy directory to remote host
  copy:
    src: /home/ubuntu/local/directory/
    dest: /home/ubuntu/remote/directory/
    remote_src: yes

In this case, Ansible recursively copies the contents of the directory on the control host to the corresponding directory on the remote host.

There are several options you can use with Ansible copy, let’s explore them.

Ansible Copy Usage Options

Let us look at different scenarios where we can use the Ansible Copy module.

Setting File Permissions and Ownership:

When copying files to remote hosts, you can set the desired permissions, ownership, and group assignments using the mode, owner, and group parameters. For example:

tasks:  
- name: Copy file and set owner and permissions
  copy:
    src: /home/ubuntu/local/file.txt
    dest: /home/ubuntu/remote/file.txt
    owner: user
    group: group
    mode: 0644

Handling File Backups:

To create backups of existing files on the remote host before overwriting them, you can use the backup parameter. If you set backup to yes, Ansible creates a backup of the remote file by appending a timestamp to the file name. For example:

tasks: 
- name: Copy file with backup
  copy:
    src: /home/ubuntu/local/file.txt
    dest: /home/ubuntu/remote/file.txt
    backup: yes

Using file checksums for Idempotent Transfers:

Idempotency ensures that the state of the system remains the same regardless of the number of times a task is executed. The copy module supports the use of checksums to perform idempotent file transfers. When you enable the checksum parameter, Ansible compares the checksums of the source and destination files to determine if a transfer is required. If the checksums match, Ansible skips the file transfer. For example:

tasks: 
- name: Copy file using checksum
  copy:
    src: /home/ubuntu/local/file.txt
    dest: /home/ubuntu/remote/file.txt
    checksum: yes

Real-World Examples

To illustrate the practical applications of the Ansible copy module, let us look at some real-world examples that demonstrate its versatility and usefulness in various scenarios.

Distributing Configuration Files:

In many infrastructure setups, you often need to distribute configuration files across multiple servers. The copy module simplifies this process by allowing you to define a central copy of the configuration file on the control host and then distribute it to the target hosts. This ensures consistency and simplifies configuration management across your infrastructure.

Below is an example of a task that distributes configuration files.

tasks: 
- name: Copy configuration file
  copy:
    src: /home/ubuntu/local/config.conf
    dest: /etc/myapp/config.conf

Deploying SSL Certificates:

If you are working with secure connections, you may need to deploy SSL certificates on your servers. The copy module makes it easy to transfer the required certificate files from the control host to the target hosts.

Below is an example of a task that distributes SSL certificates.

tasks: 
- name: Copy SSL certificate files
  copy:
    src: /home/ubuntu/local/ssl/
    dest: /etc/ssl/certs/
    remote_src: yes

Distributing Package Configurations:

If you manage package installations on multiple machines, you might need to distribute package configuration files. You can use the copy module to transfer these files to the appropriate locations on the target hosts, ensuring the correct configuration for each package.

Below is an example of a task that distributes package configuration files.

tasks: 
- name: Copy package configuration
  copy:
    src: /home/ubuntu/local/package.conf
    dest: /etc/package.conf

In this example, the package configuration file package.conf is distributed to the /etc/ directory on the target machines.

Ansible Copy vs. Ansible Fetch

The Ansible Copy and Fetch modules are both used for file transfer in Ansible, but they have different functions and use cases.

The Copy module, as mentioned earlier, is used to copy files and directories from the control machine to remote hosts. It is primarily used when you want to transfer files from the Ansible control machine to the target hosts.

The Fetch module, on the other hand, is used to copy files from remote hosts to the control machine. It allows you to retrieve files from remote hosts and store them locally on the Ansible control machine.

Here is an example of using the Fetch module in an Ansible playbook:

tasks:
- name: Fetch a file from remote host to control machine
  fetch:
    src: /home/ubuntu/remote/host/file.txt       
    dest: /home/ubuntu/control/machine/

In this example, the Fetch module is used to retrieve a file named file.txt from the remote hosts specified in the playbook's hosts section. The src parameter specifies the path of the file on the remote host, and the dest parameter specifies the destination path on the control machine.

Conclusion

The Ansible copy module is a powerful tool that simplifies the process of transferring files to remote hosts in your infrastructure. Whether you need to distribute configuration files, deploy SSL certificates, manage scripts, or customize configuration templates, the copy module offers a straightforward and efficient solution.

Overall, the Ansible Copy module simplifies the process of managing file transfers and ensures consistent configurations across multiple systems, making it a valuable asset in infrastructure automation and configuration management workflows.