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 显示的顺序相同的属性。

默认情况下假定使用 = 运算符，否则需要在字符串中包含 + 或 - 运算符。

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

支持： 完整

表示它有一个相应的操作插件，因此可以在控制器上执行部分选项

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

有关 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"

size

整数

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

已返回：成功

示例： 42

src

字符串

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

已返回：已更改

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

uid

整数

表示文件所有者的数字 ID

已返回：成功

示例： 1003

作者

  • Ansible 核心团队

  • Michael DeHaan