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 是渲染模板的日期。

注意

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

参数

参数

注释

attributes

别名：attr

字符串

生成的的文件系统对象应具有的属性。

要获取支持的标志，请查看目标系统上 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

字符串

应拥有文件系统对象的组的名称，如将馈送到 chown 一样。

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

lstrip_blocks

布尔值

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

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

选项

  • false ← (默认)

  • true

mode

任意

生成的的文件系统对象应具有的权限。

对于那些习惯使用 /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"

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

支持： 不支持

强制执行一个不按主机执行的“全局”任务，这将绕过按主机模板化以及 serial、throttle 和其他循环考虑因素

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

此操作在非锁步策略之外将无法正常工作

check_mode

支持： 完全支持

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

diff_mode

支持： 完全支持

在 diff 模式下，将返回有关已更改内容（或可能需要在 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 原生类型的信息，请参阅ansible.builtin.template查找的jinja2_native参数。

  • 在模板中包含使用日期的字符串将导致每次都将模板标记为“已更改”。

  • 从 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

字符串

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

返回值： 成功

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

gid

整数

表示所有者组的数字 ID

返回值： 成功

示例： 1003

group

字符串

所有者的组名

返回值： 成功

示例： "www-data"

md5sum

字符串

渲染文件的 MD5 校验和

返回值： 已更改

示例： "d41d8cd98f00b204e9800998ecf8427e"

mode

字符串

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

返回值： 成功

示例： "1755"

owner

字符串

所有者用户名

返回值： 成功

示例： "httpd"

大小

整数

渲染后文件的字节大小

返回值： 成功

示例： 42

src

字符串

目标机器上复制操作使用的源文件。

返回值： 已更改

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

uid

整数

表示文件所有者的数字ID

返回值： 成功

示例： 1003

作者

  • Ansible核心团队

  • Michael DeHaan