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 提供足够的 information 以正确解析它们。为了获得一致的结果，请引用八进制数（例如，'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 传递，%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 加密的 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

字符串

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

返回: 成功

示例： "1755"

owner

字符串

所有者用户名

返回: 成功

示例： "httpd"

大小

整数

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

返回: 成功

示例： 42

src

字符串

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

返回： 已更改

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

uid

整数

表示文件所有者的数字ID

返回: 成功

示例： 1003

作者

  • Ansible 核心团队

  • Michael DeHaan