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

注意

此模块是 ansible-core 的一部分，包含在所有 Ansible 安装中。在大多数情况下，即使不指定 collections 关键词，也可以使用简短的模块名称 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 是渲染模板的日期。

注意

此模块具有相应的 action 插件。

参数

参数

注释

attributes

别名：attr

字符串

生成的 filesystem 对象应具有的属性。

要获取支持的标志，请查看目标系统上 *chattr* 的手册页。

此字符串应按 *lsattr* 显示的顺序包含属性。

= 运算符被假定为默认值，否则需要在字符串中包含 + 或 - 运算符。

backup

布尔值

创建一个包含时间戳信息的备份文件，以便您可以找回原始文件，如果您不小心将其覆盖。

选项

  • false ← (默认)

  • true

block_end_string

字符串

标记块结尾的字符串。

默认值： "%}"

block_start_string

字符串

标记块开始的字符串。

默认值： "{%"

comment_end_string

字符串

在 ansible-core 2.12 中添加

标记注释语句结尾的字符串。

comment_start_string

字符串

在 ansible-core 2.12 中添加

标记注释语句开始的字符串。

dest

路径 / 必需

在远程机器上渲染模板的位置。

follow

布尔值

确定是否应跟踪符号链接。

设置为 true 时，如果存在符号链接，则将跟踪它们。

设置为 false 时，将不会跟踪符号链接。

在 Ansible 2.4 之前，这被硬编码为 true。

选项

  • false ← (默认)

  • true

force

布尔值

确定如果目标已存在则何时传输文件。

设置为 yes 时，如果内容与源不同，则替换远程文件。

设置为 no 时，只有在目标不存在时才传输文件。

选项

  • false

  • true ← (默认)

group

字符串

应拥有 filesystem 对象的组的名称，如同传递给 *chown* 一样。

如果未指定，则它使用当前用户的当前组，除非您是 root 用户，在这种情况下，它可以保留之前的拥有权。

lstrip_blocks

布尔值

确定何时应去除前导空格和制表符。

设置为 yes 时，将从行的开头到块去除前导空格和制表符。

选项

  • false ← (默认)

  • true

mode

任意

生成的 filesystem 对象应具有的权限。

对于习惯使用 * /usr/bin/chmod* 的用户，请记住模式实际上是八进制数。您必须向 Ansible 提供足够的信息才能正确解析它们。为了获得一致的结果，请引用八进制数（例如，'644' 或 '1777'），以便 Ansible 接收一个字符串，并可以将其自身从字符串转换为数字。添加前导零（例如，0755）有时有效，但在循环和其他一些情况下可能会失败。

如果不遵循这些规则中的任何一个，则向 Ansible 提供数字将导致十进制数，这将产生意外的结果。

从 Ansible 1.8 开始，模式可以指定为符号模式（例如，u+rwx 或 u=rw,g=r,o=r）。

如果未指定 mode 并且目标 filesystem 对象不存在，则在为新创建的 filesystem 对象设置模式时，将使用系统上的默认 umask。

如果未指定 mode 并且目标 filesystem 对象存在，则将使用现有 filesystem 对象的模式。

指定 mode 是确保以正确的权限创建 filesystem 对象的最佳方法。有关更多详细信息，请参阅 CVE-2020-1736。

newline_sequence

字符串

指定模板文件使用的换行符序列。

选项

  • "\\n" ← (默认)

  • "\\r"

  • "\\r\\n"

output_encoding

字符串

Ansible 2.7 中新增

覆盖用于写入由 dest 定义的模板文件的编码。

默认为 utf-8，但可以使用 Python 支持的任何编码。

为了保持一致性，源模板文件必须始终使用 utf-8 编码。

默认值： "utf-8"

owner

字符串

应该拥有文件系统对象的用户名，如同传递给 *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 时，将删除块后的第一个换行符（块，而不是变量标签！）。

选项

  • false

  • true ← (默认)

unsafe_writes

布尔值

影响何时使用原子操作来防止数据损坏或目标文件系统对象的不一致读取。

默认情况下，此模块使用原子操作来防止数据损坏或目标文件系统对象的不一致读取，但有时系统配置有误或损坏，以至于无法使用原子操作。一个例子是 docker 挂载的文件系统对象，无法在容器内以原子方式更新，只能以非安全方式写入。

此选项允许 Ansible 在原子操作失败时回退到非安全的文件系统对象更新方法（但是，它不会强制 Ansible 执行非安全写入）。

重要！非安全写入容易发生竞争条件，并可能导致数据损坏。

选项

  • false ← (默认)

  • true

validate

字符串

在将更新的文件复制到最终目标之前运行的验证命令。

使用临时文件路径进行验证，通过 '％s' 传递，必须像下面的示例一样存在。

此外，命令是安全传递的，因此 shell 功能（如扩展和管道）将不起作用。

有关如何处理比此选项提供的更复杂的验证的示例，请参见 处理复杂的验证。

variable_end_string

字符串

标记打印语句结尾的字符串。

默认值： "}}"

variable_start_string

字符串

标记打印语句开头的字符串。

默认值： "{{"

属性

属性

支持

描述

action

支持：完全支持

指示其具有相应的 action 插件，因此可以在控制器上执行某些选项部分。

async

支持：不支持

支持与 async 关键字一起使用。

bypass_host_loop

支持：不支持

强制执行不按主机执行的“全局”任务，这会绕过按主机进行的模板化以及串行、节流和其他循环考虑因素。

条件将按使用 run_once 的方式工作，使用的变量将来自第一个可用的主机。

此操作在非锁步策略之外通常不起作用。

check_mode

支持：完全支持

可以在 check_mode 下运行并返回更改状态预测，而无需修改目标，如果不受支持，则该操作将被跳过。

diff_mode

支持：完全支持

将在差异模式下返回有关已更改内容（或可能需要在 check_mode 中更改的内容）的详细信息。

platform

平台： posix

可以对其进行操作的目标操作系统/系列。

safe_file_operations

支持：完全支持

使用 Ansible 的严格文件操作函数来确保正确的权限并避免数据损坏。

vault

支持：完全支持

可以自动解密 Ansible 加密的 vault 文件。

备注

注意

  • 对于 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

将文件复制到 Windows 主机的远程位置。

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

字符串

目标文件/路径，等于传递给 *dest* 的值。

返回：成功

示例： "/path/to/file.txt"

gid

整数

表示所有者组的数字 ID。

返回：成功

示例： 1003

group

字符串

所有者的组名。

返回：成功

示例： "www-data"

md5sum

字符串

渲染文件的 MD5 校验和。

返回：已更改

示例： "d41d8cd98f00b204e9800998ecf8427e"

mode

字符串

文件的 Unix 权限，以八进制表示的字符串。

返回：成功

示例： "1755"

owner

字符串

所有者的用户名。

返回：成功

示例： "httpd"

size

整数

渲染文件的以字节为单位的大小。

返回：成功

示例： 42

src

字符串

目标机器上用于复制的源文件。

返回：已更改

示例： "/home/httpd/.ansible/tmp/ansible-tmp-1423796390.97-147729857856000/source"

uid

整数

表示文件所有者的数字 ID。

返回：成功

示例： 1003

作者

  • Ansible核心团队

  • Michael DeHaan