跳转到内容
安装

模板

控制节点上的 Jinja2、严格模式、条件、Volant 提供的过滤器、测试器和 lookup,以及模板文件如何渲染。

你的模板的工作方式与在 Ansible 中相同,只有下面这些例外。Volant 在控制节点上渲染 Jinja2,并在其上加入 Ansible 的过滤器、测试器和 lookup。

模板在严格模式下渲染。未定义的变量是错误,而不是空字符串,除非你加以防护:

- debug:
msg: "{{ release | default('latest') }}"
when: release is defined or use_latest | bool

值不是布尔值的 when 同样会被拒绝。

未定义的变量或属性,其措辞和错误链都与 ansible-core 一致:'nope' is undefined,或 object of type 'dict' has no attribute 'b'。在 task 参数中,消息位于 Finalization of task args for 'module' failed: Error while resolving value for 'arg' 之下。由 default 或 is defined 防护的读取不会抛出任何错误。

when、changed_when、failed_when 和 until 接受一个表达式或表达式列表。使用列表时,每个表达式都必须成立。

- command: /opt/app/migrate.sh
register: migrate
changed_when: "'applied' in migrate.stdout"
failed_when:
- migrate.rc != 0
- "'already up to date' not in migrate.stderr"

包在 {{ }} 里、渲染结果为字符串的条件,会像 ansible-core 2.19 那样再作为条件求值一次。当 play 的 vars 中有 healthy: "true" 时,when: "{{ healthy }}" 会运行 task。如果第一次渲染读取了来自受管主机的值,这第二次求值就不会发生:task 会失败,并给出 Encountered untrusted template or expression.。见来自主机的值绝不会被当作模板。

值是模板的变量,会在另一个模板读取它时渲染,所以过滤器或运算符总是看到最终的值:

vars:
host: example.org
url: "http://{{ host }}:8080/x"
port: "{{ 8080 }}"
tasks:
- debug:
msg: "{{ url | length }} {{ port | int + 1 }}" # 25 8081

这适用于 play、块和 task 的 vars、group_vars、role 的 defaults、vars_files、include_vars 和额外变量,也适用于包含模板的列表或映射。渲染失败的成员,在有东西读取它之前不会抛出任何错误。

读取一个没有值的名字的变量,自己也没有值:default 和 is defined 把它看作未定义。读取自身的变量,无论是直接还是通过其他变量,都会失败,并给出 Recursive loop detected in template: maximum recursion depth exceeded,在 default 后面也一样,与 ansible-core 一致。

主机数据永远不会被渲染。来自受管主机的变量,以及由它构造出的变量,仍然是文本。见来自主机的值绝不会被当作模板。

读取 vars、或调用 lookup 或 query 的变量会保持原样,在 task 使用它时才渲染。hostvars['other']['name'] 会用另一台主机自己的变量渲染该变量中的模板,与 ansible-core 一致。这次渲染中没有 hostvars。主机若持有来自受管主机的值(例如收集到的 facts),则给出原始文本。

类别 名称
过滤器 default / d, bool, int, float, mandatory, ternary, combine, dict2items, items2dict, to_json, to_nice_json, from_json, to_yaml, to_nice_yaml, from_yaml, basename, dirname, split, regex_replace, regex_search, regex_findall, regex_escape, extract, b64encode, b64decode, comment, difference, intersect, union, flatten, to_uuid, type_debug, quote
测试器 truthy, falsy, match, search, regex, contains, changed / change, failed / failure, succeeded / success / successful, skipped / skip, version(以及 version_compare)
Lookup env, file, vars, varnames, pipe, first_found, fileglob, template, inventory_hostnames, unvault(以及 query 和 q 调用形式)
全局函数 now, lipsum
来自 ansible.utils ansible.utils.ipwrap 过滤器,只能用这个完整名称

这个列表中的每个过滤器、测试器和 lookup,也都能以它的 ansible.builtin.* 名称应答,所以 {{ data | ansible.builtin.to_json }} 可以工作。不在这个列表里的过滤器、测试器或 lookup,会用 ansible-core 自己的代码在 Python 中运行,见需要 Python 的过滤器、测试器和 lookup。这也包括其他 collection 的插件。

first_found、fileglob 和 template 沿着 ansible_search_path 查找文件。在 role 的 task 中,这条路径依次是 role 的目录、task 所在文件的目录,然后是 playbook 的目录。在 role 之外,则是 playbook 的目录。role_path 在 role 的 task 中设置,在 role 之外未定义。fileglob 先在每个条目的 files/ 下尝试相对模式,然后在条目本身里尝试,第一个有匹配的条目胜出。它只返回文件,结果已排序,只有一个匹配时以字符串返回。

now() 给出的是控制节点上的日期和时间,绝不是受管主机上的,lipsum() 给出随机的填充文本。它们的参数和结果见模板语言参考。

需要 Python 的过滤器、测试器和 lookup

Section titled “需要 Python 的过滤器、测试器和 lookup”

Volant 自己用 Rust 实现常用的过滤器、测试器和 lookup。ansible-core 2.19.12 或某个 collection 提供的其他所有过滤器、测试器和 lookup,都在控制节点上的 Python 进程中运行,使用插件自己的代码,所以结果与 ansible-core 给出的一致。

只用 Rust 版本的 play,永远不会为模板启动 Python。Python 进程在第一次需要它的调用时启动;如果某个循环用到只有 ansible-core 才有的 lookup,则在运行开始时就启动,然后为运行的其余部分服务。启动大约需要 0.55 秒,每次运行只付一次,用 hash 测得。

Volant 没有某个名称的 Rust 版本时,这个名称就需要 Python。对等性页面把这些行标为 runs,并附上说明 “through the Python helper; needs the plugin’s Python libraries”。例子有 hash、password_hash、json_query 和 ipaddr 过滤器,以及 lines 和 url lookup。

有 Rust 版本的名称,无论怎么称呼,都不会到达 Python。ansible.utils.ipwrap 仍在 Rust 中。vault 的过滤器、测试器和 lookup 同样绝不会交给 Python:vault 密码留在控制节点进程内。见 Vault。

控制节点需要带有 ansible-core 的 Python 3。如果没有,Volant 会安装自己的托管运行时。

插件还需要它导入的东西。json_query 需要 jmespath,ipaddr 需要 netaddr,password_hash 需要 passlib,collection 的插件需要那个 collection。所有这些都必须安装在 Volant 运行的那个解释器里。托管运行时只包含 ansible-core 及其依赖,没有别的,所以对于这些名称,请把 VOLANT_PYTHON 指向你自己装有这些包的环境。没有它们时,task 会失败,并给出插件自己的消息。

设置了 VOLANT_PYTHON 时,Volant 只使用它,不用别的。否则它依次尝试托管运行时、当前激活的虚拟环境、PATH 上的 python3,都不可用时安装托管运行时。没有 ansible-core 的解释器会按名称被拒绝,消息会说明尝试过哪些解释器。调用需要 Python 的名称的 task 随后会失败,消息类似 filter 'hash' needs the Python helper, which could not start: …,后面跟着原因,运行以非零退出码结束。

在 Python 中运行的过滤器列出了其他失败情形,以及 Python 收到的内容。

来自主机的值绝不会被当作模板

Section titled “来自主机的值绝不会被当作模板”

你写的模板是代码。受管主机发回的值是数据,永远不会在控制节点上作为模板运行。

  • 不可信的值是 register 和模块结果、收集到的 facts、set_fact 的值,以及 lookup('file')、lookup('pipe')、lookup('env') 和 lookup('template') 的结果。
  • 可信的值是 playbook 自带的那些:play 和 task 的 vars、--extra-vars、inventory 变量、vars_files 和 include_vars。!unsafe 把其中一个标记为数据。
  • 不可信的值只渲染一次。如果结果看起来又像模板,它仍然是文本。
  • 会把主机的值作为表达式求值的条件或 debug: var:,会失败,并给出 Encountered untrusted template or expression.
  • 在 debug: var:、assert 的 that、when、changed_when、failed_when 或 until 中写在 !unsafe 下的表达式,也会以同样方式失败。

模板语言参考有完整的规则和示例。

template 模块和 lookup('template') 共用同一次渲染,它与 task 参数的渲染有一点不同:它只渲染文件的文本一次。task 参数还要经过更多轮,这就是渲染后仍含有 {{ ... }} 的值可以被再次当作模板读取的原因。模板文件没有这第二轮,所以受管主机贡献的值会以纯文本的形式进入写出的文件,永远不会作为它自己的模板运行。

它接受 template 模块读取的这些选项:

选项 默认值 作用
trim_blocks 开 删除块标签之后的第一个换行。
lstrip_blocks 关 去掉块标签所在行中,标签之前的空白。
newline_sequence \n 写出文件的换行符:\n、\r 或 \r\n,可以转义,也可以是字面字符。
variable_start_string、variable_end_string {{、}} 表达式两侧的标记。
block_start_string、block_end_string {%、%} 语句两侧的标记。
comment_start_string、comment_end_string {#、#} 注释两侧的标记。
output_encoding utf-8 写出文件的编码。仅适用于 template。

lookup('template') 接受四个变量和注释分隔符以及 trim_blocks,别的都不接受。

只由一个节点组成的模板(单独一个 {{ }},前后没有别的内容),会让 lookup('template') 得到该表达式的值并保留其类型,与 ansible-core 相同:{{ {'a': 1} }} 得到一个映射。主体只有一个节点的宏也同样返回该值。

自定义分隔符会替换默认分隔符:设置了 variable_start_string: '[[' 时,文件中的 {{ 就是纯文本。三个起始字符串必须互不相同。不包含这三个起始字符串中任何一个的文本不是模板,会原样写出,包括换行符,无论 newline_sequence 怎么设置。

模板文件的第一行可以覆盖这些选项。它以 #jinja2: 开头,包含按逗号分隔的 key: value 对,值是 Python 字面量:

#jinja2: variable_start_string:'[%', variable_end_string:'%]', trim_blocks: False

可用的键是六个分隔符、trim_blocks、lstrip_blocks、newline_sequence 和 keep_trailing_newline。这一行优先于 task 的选项。错误的键、错误的类型或两个相同的起始字符串,会让渲染失败,消息与 ansible-core 一致。这一行会从输出中删除。不在文件最开头的 #jinja2: 是纯文本。

output_encoding 可以写出 UTF-8、带签名的 UTF-8、Latin-1、ASCII、cp1252、ISO 8859-15、UTF-16 和 UTF-32,使用 Python 认识的名称和别名(latin-1、iso8859_1、utf_16_le、windows-1252)。没有指定字节序的 UTF-16 和 UTF-32 会写入字节顺序标记,之后使用小端序。编码无法容纳的字符会让 task 失败,消息来自 Python,指出该字符及其位置。其他任何编码都会按名称被拒绝。

文件自己结尾的换行符在渲染后得以保留。Action 插件介绍了 template 模块做的其余事情。

raw 块或表达式构造出的花括号如何保持字面不变,见字面花括号。

这些缺口影响的 playbook 最多。模板语言参考列出了渲染、模板文件和字节方面的缺口。

  • b64encode 和 b64decode 的 encoding 接受 utf-8、utf-8-sig、latin-1、ascii、cp1252、iso-8859-15、utf-16 和 utf-32,可使用它们在 Python 中的任一名称。其他编解码器会以 unknown encoding 失败。
  • password_hash、json_query 和 ipaddr 需要 Python 包 passlib、jmespath 和 netaddr。托管运行时不带它们,见要安装什么。

模块可能返回这样的整数,例如 RSA 密钥的模数。Volant 在结果、变量、string、to_json 和 from_json 中保留它的每一位数字。在比较运算符、min、max、sort、unique 和 list.sort() 中,它按值与任何数字比较。

  • 运算符 +、-、*、/、//、% 和 **,以及 abs 和 round 过滤器,会拒绝宽操作数。宽于 128 位的结果是错误。
  • 超过 4300 位数字的 YAML 整数会被拒绝。传给 int 的同样大小的文本也一样,此时 int 回答它的默认值,与 Python 3.11 及更高版本一致。

要对这样的值做算术运算,请使用模块,或使用 command 配合 python3 -c,并把宽值保留为文本。