ansible.builtin.template 模块 - 将文件模板输出到目标主机

注意

此模块是 ansible-core 的一部分，包含在所有 Ansible 安装中。在大多数情况下，即使没有指定集合关键字，您也可以使用简短的模块名称 template。但是，我们建议您使用完全限定的集合名称 (FQCN) ansible.builtin.template 以便轻松链接到模块文档并避免与可能具有相同模块名称的其他集合冲突。

概要 

模板由 Jinja2 模板语言处理。
有关模板格式的文档可以在模板设计人员文档中找到。
下面列出的其他变量可以在模板中使用。
ansible_managed（可通过 ansible.cfg 的 defaults 部分配置）包含一个字符串，可用于描述模板名称、主机、模板文件的修改时间和所有者 UID。
template_host 包含模板机器的节点名称。
template_uid 是所有者的数字用户 ID。
template_path 是模板的路径。
template_fullpath 是模板的绝对路径。
template_destpath 是模板在远程系统上的路径（在 2.8 中添加）。
template_run_date 是渲染模板的日期。

注意

此模块具有相应的操作插件。

参数 

参数	注释
attributes 别名：attr 字符串	结果文件系统对象应具有的属性。要获取支持的标志，请查看目标系统上 `chattr` 的手册页。此字符串应按 `lsattr` 显示的顺序包含属性。 `=` 运算符被假定为默认值，否则需要在字符串中包含 `+` 或 `-` 运算符。
备份布尔	创建一个备份文件，其中包括时间戳信息，以便您可以检索原始文件（如果您不小心将其覆盖）。选择 `false` ← (默认) `真的`
block_end_string 字符串	标记块结尾的字符串。默认值： `"%}"`
block_start_string 字符串	标记块开始的字符串。默认值： `"{%"`
comment_end_string 字符串在 ansible-core 2.12 中添加	标记注释语句结尾的字符串。
comment_start_string 字符串在 ansible-core 2.12 中添加	标记注释语句开始的字符串。
目的地路径 / 必需	在远程机器上渲染模板的位置。
跟随布尔	确定是否应遵循符号链接。当设置为 `true` 时，将遵循符号链接（如果存在）。当设置为 `false` 时，将不遵循符号链接。在 Ansible 2.4 之前，这是硬编码为 `true`。选择 `false` ← (默认) `真的`
力量布尔	确定在传输文件时，目标文件是否已存在。当设置为 `yes` 时，如果内容与源内容不同，则替换远程文件。当设置为 `no` 时，只有在目标不存在的情况下才会传输文件。选择 `错误的` `true` ← (默认)
组字符串	应拥有文件系统对象的组的名称，如传递给 `chown` 一样。当未指定时，它使用当前用户的当前组，除非您是 root，在这种情况下，它可以保留之前的拥有权。
lstrip_blocks 布尔	确定何时应剥离前导空格和制表符。当设置为 `yes` 时，从一行开始到块的开头剥离前导空格和制表符。选择 `false` ← (默认) `真的`
模式任何	结果文件系统对象应具有的权限。对于习惯使用 `/usr/bin/chmod` 的人来说，请记住模式实际上是八进制数。您必须为 Ansible 提供足够的信息才能正确解析它们。为了获得一致的结果，请引用八进制数（例如，`'644'` 或 `'1777'`），以便 Ansible 接收一个字符串并可以自行将字符串转换为数字。添加前导零（例如，`0755`）有时有效，但在循环和其他某些情况下可能会失败。如果为 Ansible 提供一个数字，而不遵循上述任何规则，则最终将得到一个十进制数，这将导致意外结果。从 Ansible 1.8 开始，模式可以指定为符号模式（例如，`u+rwx` 或 `u=rw,g=r,o=r`）。如果未指定 `mode`，并且目标文件系统对象不存在，则在设置新创建的文件系统对象的模式时，将使用系统上的默认 `umask`。如果未指定 `mode`，并且目标文件系统对象存在，则将使用现有文件系统对象的模式。指定 `mode` 是确保文件系统对象以正确权限创建的最佳方法。有关更多详细信息，请参阅 CVE-2020-1736。
newline_sequence 字符串	指定用于模板文件的换行符序列。选择 `"\\n"` ← (默认) `"\\r"` `"\\r\\n"`
output_encoding 字符串在 Ansible 2.7 中添加	覆盖用于写入由 `dest` 定义的模板文件的编码。它默认为 `utf-8`，但可以使用 python 支持的任何编码。源模板文件必须始终使用 `utf-8` 编码，以确保一致性。默认值： `"utf-8"`
所有者字符串	应拥有文件系统对象的用户的名称，如传递给 `chown` 一样。当未指定时，它使用当前用户，除非您是 root，在这种情况下，它可以保留之前的拥有权。指定数字用户名将被假定为用户 ID 而不是用户名。避免使用数字用户名以避免这种混淆。
selevel 字符串	SELinux 文件系统对象上下文的级别部分。这是 MLS/MCS 属性，有时也称为 `range`。当设置为 `_default` 时，它将使用策略中的 `level` 部分（如果可用）。
serole 字符串	SELinux 文件系统对象上下文的角色部分。当设置为 `_default` 时，它将使用策略中的 `role` 部分（如果可用）。
setype 字符串	SELinux 文件系统对象上下文的类型部分。当设置为 `_default` 时，它将使用策略中的 `type` 部分（如果可用）。
seuser 字符串	SELinux 文件系统对象上下文的用户部分。默认情况下，它使用 `system` 策略（如果适用）。当设置为 `_default` 时，它将使用策略中的 `user` 部分（如果可用）。
src 路径 / 必需	Ansible 控制器上 Jinja2 格式化模板的路径。这可以是相对路径或绝对路径。该文件必须使用 `utf-8` 编码，但 `output_encoding` 可用于控制输出模板的编码。
trim_blocks 布尔	确定何时应从块中删除换行符。当设置为 `yes` 时，将删除块后的第一个换行符（块，而不是变量标记！）。选择 `错误的` `true` ← (默认)
unsafe_writes 布尔	影响何时使用原子操作来防止目标文件系统对象的数据损坏或不一致读取。默认情况下，此模块使用原子操作来防止目标文件系统对象的数据损坏或不一致读取，但有时系统以阻止此操作的方式配置或损坏。一个例子是 docker 挂载的文件系统对象，它们不能在容器内部以原子方式更新，只能以不安全的方式写入。此选项允许 Ansible 在原子操作失败时回退到不安全的文件系统对象更新方法（但是，它不会强制 Ansible 执行不安全写入）。重要！不安全的写入容易出现竞争条件，并可能导致数据损坏。选择 `false` ← (默认) `真的`
validate 字符串	在将更新后的文件复制到最终目标之前要运行的验证命令。使用临时文件路径进行验证，该路径通过 `%s` 传递，该路径必须存在，如下面的示例所示。此外，命令以安全的方式传递，因此 shell 功能（例如扩展和管道）将不起作用。有关如何处理比此选项提供的更复杂的验证的示例，请参阅处理复杂的验证.
variable_end_string 字符串	标记打印语句结束的字符串。默认值： `"}}"`
variable_start_string 字符串	标记打印语句开始的字符串。默认值： `"{{"`

属性 

属性	支持	描述
action	支持：完全支持	指示它具有相应的操作插件，因此某些选项部分可以在控制器上执行。
async	支持：不支持	支持与 `async` 关键字一起使用。
bypass_host_loop	支持：不支持	强制执行不按主机执行的“全局”任务，这将绕过按主机模板化和序列化、节流和其他循环考虑因素。条件将按使用 `run_once` 的方式工作，使用的变量将来自第一个可用主机。此操作在非锁步策略之外将无法正常工作。
check_mode	支持：完全支持	可以在 check_mode 中运行并返回更改状态预测，而不会修改目标，如果不受支持，则该操作将被跳过。
diff_mode	支持：完全支持	将在 diff 模式下返回有关发生了什么更改（或可能需要在 check_mode 中更改）的详细信息。
platform	平台： posix	可以对其进行操作的目标操作系统/系列。
safe_file_operations	支持：完全支持	使用 Ansible 的严格文件操作功能来确保正确的权限并避免数据损坏。
vault	支持：完全支持	可以自动解密 Ansible 拱顶文件。

备注 

注意

对于 Windows，您可以使用 ansible.windows.win_template，它默认使用 \r\n 作为 newline_sequence。
jinja2_native 设置无效。本机类型从未在 ansible.builtin.template 模块中使用，该模块是专为生成文本文件而设计的。要使用模板并利用 Jinja2 本机类型，请参阅 jinja2_native ansible.builtin.template 查找的参数。
在模板中包含使用日期的字符串会导致模板每次都被标记为“已更改”。
从 Ansible 0.9 开始，模板使用 trim_blocks=True 加载。
此外，您可以通过在模板文件中添加一个特殊的标题来覆盖 jinja2 设置。即 #jinja2:variable_start_string:'[%', variable_end_string:'%]', trim_blocks: False，它将变量插值标记更改为 [% var %] 而不是 {{ var }}。这是防止评估看起来像但不是 Jinja2 的东西的最佳方法。
要在文件中查找字节顺序标记，请在 Windows 上使用 Format-Hex <file> -Count 16，在 Linux 上使用 od -a -t x1 -N 16 <file>。

另请参阅 

另请参阅

ansible.builtin.copy: 将文件复制到远程位置。
ansible.windows.win_copy: ansible.windows.win_copy 模块的官方文档。
ansible.windows.win_template: ansible.windows.win_template 模块的官方文档。

示例 

- name: Template a file to /etc/file.conf
  ansible.builtin.template:
    src: /mytemplates/foo.j2
    dest: /etc/file.conf
    owner: bin
    group: wheel
    mode: '0644'

- name: Template a file, using symbolic modes (equivalent to 0644)
  ansible.builtin.template:
    src: /mytemplates/foo.j2
    dest: /etc/file.conf
    owner: bin
    group: wheel
    mode: u=rw,g=r,o=r

- name: Copy a version of named.conf that is dependent on the OS. setype obtained by doing ls -Z /etc/named.conf on original file
  ansible.builtin.template:
    src: named.conf_{{ ansible_os_family }}.j2
    dest: /etc/named.conf
    group: named
    setype: named_conf_t
    mode: '0640'

- name: Create a DOS-style text file from a template
  ansible.builtin.template:
    src: config.ini.j2
    dest: /share/windows/config.ini
    newline_sequence: '\r\n'

- name: Copy a new sudoers file into place, after passing validation with visudo
  ansible.builtin.template:
    src: /mine/sudoers
    dest: /etc/sudoers
    validate: /usr/sbin/visudo -cf %s

- name: Update sshd configuration safely, avoid locking yourself out
  ansible.builtin.template:
    src: etc/ssh/sshd_config.j2
    dest: /etc/ssh/sshd_config
    owner: root
    group: root
    mode: '0600'
    validate: /usr/sbin/sshd -t -f %s
    backup: yes

返回值 

常见的返回值在此处有记录，以下是此模块特有的字段。

键	描述
checksum 字符串	渲染文件的 SHA1 校验和返回值：始终示例： `"373296322247ab85d26d5d1257772757e7afd172"`
目的地字符串	目标文件/路径，等于传递给 dest 的值。返回值：成功示例： `"/path/to/file.txt"`
gid 整数	表示所有者组的数字 ID 返回值：成功示例： `1003`
组字符串	所有者的组名返回值：成功示例： `"www-data"`
md5sum 字符串	渲染文件的 MD5 校验和返回值：已更改示例： `"d41d8cd98f00b204e9800998ecf8427e"`
模式字符串	文件的八进制表示形式的 Unix 权限，以字符串形式表示返回值：成功示例： `"1755"`
所有者字符串	所有者的用户名返回值：成功示例： `"httpd"`
size 整数	渲染文件的字节大小返回值：成功示例： `42`
src 字符串	目标机器上用于复制的源文件。返回值：已更改示例： `"/home/httpd/.ansible/tmp/ansible-tmp-1423796390.97-147729857856000/source"`
uid 整数	表示文件所有者的数字 ID 返回值：成功示例： `1003`

作者

Ansible 核心团队
迈克尔·德汉