Ansible is one of the most powerful, free, open-source configuration management, automation, and orchestration tools.
One of the significant features of Ansible is its cross-platform management capabilities. Ansible allows us to automatically manage both Unix-based and Windows machines in simple declarative language and commands.
In this post, we will learn about the win_copy module, a powerful Ansible module that is developed for Windows systems only.
Ansible Win_Copy Module
The win_copy module is part of Ansible’s Windows collection which contains a set of modules that is developed for interacting and managing the Windows machines using Ansible.
The win_copy module, in this case, allows us to use Ansible to copy the files to and from the Windows machines with ease. Using this module, we can transfer the files directly from an Ansible controller or any other specified location to a remote Windows host.
The module supports various parameters that allow us to customize its functionality. The following are some essential parameters that you need to know before using this module:
Src – It specifies a local path to a file to copy to the remote server; it can be absolute or relative. If the path provides is a directory, the module copies the directory recursively to the specified destination.
Dest – It defines the remote absolute path to copy the specified files. If the src parameter is a directory, the dest parameter must be a directory too.
Backup – If it is set to true, the module creates a backup file, including the timestamp information, to get the original file back if clobbered incorrectly.
The given parameters are some of the most common parameters that you must interact with when working with the win_copy module. You can reference the documentation to check the other supported parameters.
Installing the Ansible Collection
Before using the win_copy module, we must ensure that the appropriate Ansible collection is installed. This collection provides the required modules to manage the Windows machines. We can install it using the ansible-galaxy command:
Let us now proceed and explore some basics on how to use the win_copy module.
Using the Win_Copy Module
The most straightforward method of using the win_copy module is to copy a file from your Ansible control machine to a Windows target.
- name: Copy config.ini to Windows
This should copy the “config.ini” file that is specified on the controller filesystem to the path that is defined in the Windows node.
Using with Content Parameter
We also have access to the content parameter in the win_copy module that allows us to specify the inline content instead of the “src” file.
An example usage is as follows:
- name: Create a file with content
content: "Hello, World!"
Copying the Directories
To copy an entire directory, specify the directory path for “src” as demonstrated in the following playbook example:
- name: Copy the example directory to C:\temp\example
Note: The trailing slash at the end of the “src” directory path is essential as it tells Ansible to copy the directory recursively, including the “src” directory itself.
Preserving the Filenames
To copy a given file while preserving the filename, you can provide the “dest” parameter to the target directory as follows:
In this case, the module copies the “config.ini” file to the C:\Temp under the same name as the original file.
To create a backup of the file before copying, you can use the backup parameter as follows:
This should copy the “config.ini” file to the specified location while renaming the destination file. It also creates a file backup in case it gets destroyed.
We can use the “when” clause to copy a file only when a specific condition is met as demonstrated in the following example:
Using the Check Mode
If you first want to test out the changes that occur when running a given playbook, you can use the –check flag when running the playbook. This forces the win_copy module to report what changes would occur without actually performing them.
Copying the Large Files
For large files, consider using the “ansible.windows.win_get_url” module instead. It lets us fetch the large files directly from the remote locations to the Windows targets without routing them through the Ansible controller.
We learned how to use the win_copy module in Ansible to copy the files from an Ansible controller or any specified location to a Windows target host.