ansible.windows.win_template – Template a file out to a remote server
ansible.windows.win_template – Template a file out to a remote server
Note
This plugin is part of the ansible.windows collection (version 1.3.0).
To install it use: ansible-galaxy collection install ansible.windows
.
To use it in a playbook, specify: ansible.windows.win_template
.
Synopsis
- Templates are processed by the Jinja2 templating language.
- Documentation on the template formatting can be found in the Template Designer Documentation.
- Additional variables listed below can be used in templates.
ansible_managed
(configurable via thedefaults
section ofansible.cfg
) contains a string which can be used to describe the template name, host, modification time of the template file and the owner uid.template_host
contains the node name of the template’s machine.template_uid
is the numeric user id of the owner.template_path
is the path of the template.template_fullpath
is the absolute path of the template.template_destpath
is the path of the template on the remote system (added in 2.8).template_run_date
is the date that the template was rendered.
Parameters
Parameter | Choices/Defaults | Comments |
---|---|---|
backup boolean |
|
Determine whether a backup should be created. When set to |
block_end_string string |
Default: "%}" |
The string marking the end of a block. |
block_start_string string |
Default: "{%" |
The string marking the beginning of a block. |
dest path / required |
Location to render the template to on the remote machine. | |
force boolean |
|
Determine when the file is being transferred if the destination already exists. When set to When set to |
lstrip_blocks boolean |
|
Determine when leading spaces and tabs should be stripped. When set to This functionality requires Jinja 2.7 or newer. |
newline_sequence string |
|
Specify the newline sequence to use for templating files. |
output_encoding string |
Default: "utf-8" |
Overrides the encoding used to write the template file defined by It defaults to The source template file must always be encoded using |
src path / required |
Path of a Jinja2 formatted template on the Ansible controller. This can be a relative or an absolute path. The file must be encoded with | |
trim_blocks boolean |
|
Determine when newlines should be removed from blocks. When set to |
variable_end_string string |
Default: "}}" |
The string marking the end of a print statement. |
variable_start_string string |
Default: "{{" |
The string marking the beginning of a print statement. |
Notes
Note
- Including a string that uses a date in the template will result in the template being marked ‘changed’ each time.
- Also, you can override jinja2 settings by adding a special header to template file. i.e.
#jinja2:variable_start_string:'[%', variable_end_string:'%]', trim_blocks: False
which changes the variable interpolation markers to[% var %]
instead ofTemplate:Var
. This is the best way to prevent evaluation of things that look like, but should not be Jinja2. - Using raw/endraw in Jinja2 will not work as you expect because templates in Ansible are recursively evaluated.
- To find Byte Order Marks in files, use
Format-Hex <file> -Count 16
on Windows, and useod -a -t x1 -N 16 <file>
on Linux. - Beware fetching files from windows machines when creating templates because certain tools, such as Powershell ISE, and regedit’s export facility add a Byte Order Mark as the first character of the file, which can cause tracebacks.
- You can use the ansible.windows.win_copy module with the
content:
option if you prefer the template inline, as part of the playbook. - For Linux you can use ansible.builtin.template which uses ‘\n’ as
newline_sequence
by default.
See Also
See also
- ansible.windows.win_copy
- The official documentation on the ansible.windows.win_copy module.
- ansible.builtin.copy
- The official documentation on the ansible.builtin.copy module.
- ansible.builtin.template
- The official documentation on the ansible.builtin.template module.
Examples
- name: Create a file from a Jinja2 template
ansible.windows.win_template:
src: /mytemplates/file.conf.j2
dest: C:\Temp\file.conf
- name: Create a Unix-style file from a Jinja2 template
ansible.windows.win_template:
src: unix/config.conf.j2
dest: C:\share\unix\config.conf
newline_sequence: '\n'
backup: yes
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key | Returned | Description |
---|---|---|
backup_file string |
if backup=yes |
Name of the backup file that was created.
Sample: C:\Path\To\File.txt.11540.20150212-220915.bak |
Authors
- Jon Hawkesworth (@jhawkesworth)
© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.11/collections/ansible/windows/win_template_module.html