ansible基础-Jinja2模版 | 过滤器

时间:2023-01-17 17:03:50

Jinja2模版介绍

注:本文demo使用ansible2.7稳定版

ansible基础-变量的「8.2 模版使用变量」章节中关于模版与变量也有所提及,有兴趣的同学可以去回顾一下。

ansible通过Jinja2模版来实现动态表达式和变量的引用,模版的执行都是在ansible控制端完成的,所以理论上python的jinja2模块在控制端存在就能满足需求。

Jinja2模版都可以怎么使用?(分类)

  1. playbook文件中引用Jinja2模版实现动态表达式和变量的引用。
  2. 模版文件(roles/templates/xxx.j2)中引用Jinja2模版实现配置文件内容的拼接。

为什么要使用Jinja2模版?(好处)

  1. 使用过滤器、插件、测试变量等能够非常简单的实现一些小型的函数运算,使部署代码更加简洁高效。
  2. 适用性更加广泛,使部署代码更加灵活。

相比较于python原生的Jinja2模版,ansible扩展了很多过滤器和测试变量,同时也添加了一个新的插件「lookups」。

关于jinja2模版的基础语法和使用,因为篇幅原因,这里不再扩展。本文着重介绍下过滤器。

数据格式化过滤器

过滤器「to_json」「to_yaml」,将变量转换为json和yaml格式

{{ some_variable | to_json }}
{{ some_variable | to_yaml }}

过滤器「to_nice_json」「to_nice_yaml」,将变量转换为更加友好的json和yaml格式

{{ some_variable | to_nice_json }}
{{ some_variable | to_nice_yaml }}

也可以自定义缩进的大小

{{ some_variable | to_nice_json(indent=) }}
{{ some_variable | to_nice_yaml(indent=) }}

过滤器「from_json」「from_yaml」,从已经格式化好了的变量读取数据:

{{ some_variable | from_json }}
{{ some_variable | from_yaml }}

「from_json」示例,从file.json文件读取json数据:

tasks:
- shell: cat /some/path/to/file.json
register: result
- set_fact:
myvar: "{{ result.stdout | from_json }}"

过滤器「from_yaml_all」,用来解析YAML多文档文件

tasks:
- shell: cat /some/path/to/multidoc-file.yaml
register: result
- debug:
msg: '{{ item }}'
loop: '{{ result.stdout | from_yaml_all | list }}'

YAML多文档文件指一个文件中包含多个yaml数据文档,例如:

---
part_one: one
... ---
part_two: two
...

变量强制定义过滤器

当我们引用一个未被定义的变量时,ansible默认会报错,当然我们可以通过更改ansible.cfg配置项的方式关闭这种机制(即设置[defaults]字段下的error_on_undefined_vars = False)。

在关闭这个机制的情况下,如果我们想让ansible强制检查某个变量是否定义,可以使用「mandatory」过滤器,写法如下:

{{ variable | mandatory }}

此时,如果变量「variable」被定义了,则引用,否则会报错:

fatal: [node1]: FAILED! => {"msg": "Mandatory variable 'aaa' not defined."}

变量默认值过滤器

「default」过滤器可以为未定义变量设置默认值,类似于roles/defaults/main.yaml里定义的变量,优先级最低(变量优先级参考ansible基础-变量)。

示例如下:

{{ some_variable | default() }}

另外,如果我们想将变量参数是false、False和空(None)视为未定义,则必须给defaults过滤器第二参数位置加上「true」:

{{ lookup('env', 'MY_USER') | default('admin', true) }}

上面示例中表示:从环境变量中查找「MU_USER」变量,如果变量值为false、False、空(None)、未定义则将其设置为「admin」。否则引用之前被定义的参数。

可删除参数过滤器

过滤器「omit」:在使用模块的时候,有些参数的存在与否可以取决于变量是否被定义:

- name: touch files with an optional mode
file: dest={{ item.path }} state=touch mode={{ item.mode | default(omit) }}
loop:
- path: /tmp/foo
- path: /tmp/bar
- path: /tmp/baz
mode: ""

上面示例表示:变量中如果定义了变量「mode」,file模块则使用mode参数,否则就不使用。

执行结果为「/tmp/foo」和「/tmp/bar」文件使用默认权限,「/tmp/baz」文件使用「0444」权限。

列表过滤器

过滤器「min」,获取最小值元素

{{ list1 | min }}

过滤器「max」,获取最大值元素

{{ [, , ] | max }}

过滤器「flatten」,扁平化列表元素

{{ [, [, ] ] | flatten }}

转换结果为:

[, ,  ]

过滤器「flatten」,并且指定级别

{{ [, [, []] ] | flatten(levels=) }}

只转换一级的列表元素,结果为:

[, , [] ]

过滤器「unique」,给列表元素去重

{{ list1 | unique }}

过滤器「union」,合并两个列表后去重

{{ list1 | union(list2) }}

过滤器「intersect」,取两个列表相同的元素

{{ list1 | intersect(list2) }}

过滤器「difference」,去掉list1中与list2相同的元素,返回list1中剩余的元素

{{ list1 | difference(list2) }}

过滤器「symmetric_difference」,去掉list1与list2相同的元素,返回list1和list2剩余元素的集合

{{ list1 | symmetric_difference(list2) }}

操作列表过滤器zip和zip_longest

过滤器「zip」,使两个列表元素递归的融合,生成一个「itertools.izip」生成器对象。

通常后面加上「list」过滤器来使用,表示list1[0]元素与list2[0]元素组合,作为新列表的第一个元素;list1[1]元素与list2[1]元素组合,作为新列表的第二个元素 ,以此类推…… 新列表元素个数以list1和list2中元素个数较少者为准。

如果文字描述不懂,看下面示例就懂了:

- name: give me list combo of two lists
debug:
msg: "{{ [1,2,3,4,5] | zip(['a','b','c','d','e','f']) | list }}"

转换结果为:

    "msg": [
[
,
"a"
],
[
,
"b"
],
[
,
"c"
],
[
,
"d"
],
[
,
"e"
]
]

过滤器「zip_longest」,与「zip」过滤器合并原理相似,「zip_longest」可以对更多的列表进行操作,且新列表元素个数以被操作列表中元素个数最多者为准,此时就需要指定「fillvalue」参数作为补位填充。示例如下:

{{ [,,] | zip_longest(['a','b','c','d','e','f'], [, , ], [,,],fillvalue='X') | list }}

转换结果为:

 "msg": [
[
,
"a",
, ],
[
,
"b",
, ],
[
,
"c",
, ],
[
"X",
"d",
"X",
"X"
],
[
"X",
"e",
"X",
"X"
],
[
"X",
"f",
"X",
"X"
]
]

转换结果

操作列表过滤器subelements

过滤器「subelements」,操作对象为列表,摘取列表中的一个元素(通常为一个字典),将这个字典元素作为原始列表的新元素,其他元素保持不变。

{{ users | subelements('groups', skip_missing=True) }}

上面语句会将:

users:
- name: alice
authorized:
- /tmp/alice/onekey.pub
- /tmp/alice/twokey.pub
groups:
- wheel
- docker
- name: bob
authorized:
- /tmp/bob/id_rsa.pub
groups:
- docker

转换为:

-
- name: alice
groups:
- wheel
- docker
authorized:
- /tmp/alice/onekey.pub
- /tmp/alice/twokey.pub
- wheel
-
- name: alice
groups:
- wheel
- docker
authorized:
- /tmp/alice/onekey.pub
- /tmp/alice/twokey.pub
- docker
-
- name: bob
authorized:
- /tmp/bob/id_rsa.pub
groups:
- docker
- docker

列表与字典互相转换过滤器

过滤器「dict2items」,将字典变量转换为列表变量

{{ dict | dict2items }}

例如,可以将

tags:
Application: payment
Environment: dev

转换为:

- key: Application
value: payment
- key: Environment
value: dev

过滤器「items2dict」,将列表变量转换为字典变量,默认情况下,列表元素必须有「key:」和「 value」。例如:

tags:
- key: Application
value: payment
- key: Environment
value: dev

转换为:

Application: payment
Environment: dev

当然我们也可以认为指定「key:」「value」的替代参数:

{{ tags | items2dict(key_name='key_spec', value_name='value_spec') }}

随机Mac地址数过滤器

过滤器「random_mac」,在一个MAC地址前缀的基础上,随机生成mac地址。

"{{ '52:54:00' | random_mac }}"
# => '52:54:00:ef:1c:03'

注:如果给出的MAC地址前缀格式有问题,ansible会报错。

随机数过滤器

过滤器「random」,用于生成随机数,操作对象可以是一个列表也可以是一个数字。

从列表里随机获取一个数值:

"{{ ['a','b','c'] | random }}"
# => 'c'

从数字0到60之间获取一个随机数:

"{{ 60 | random }} * * * * root /script/from/cron"
# => '21 * * * * root /script/from/cron'

从数字10到100之间获取一个随机数,间隔设置为10:

{{  | random(, ) }}
# =>
{{ | random(start=, step=) }}
# =>

添加「seed」参数可以根据指定变量获取一个随机数,用于满足幂等性需求:

"{{ 60 | random(seed=inventory_hostname) }} * * * * root /script/from/cron"

打乱列表顺序过滤器

过滤器「shuffle」,用于给一个列表重新排序,每次排序随机:

{{ ['a','b','c'] | shuffle }}
# => ['c','a','b']
{{ ['a','b','c'] | shuffle }}
# => ['b','c','a']

添加「seed」参数可以根据指定变量获取一个随机排序,用于满足幂等性要求,此时,每次执行playbook获取到的列表顺序是固定的:

{{ ['a','b','c'] | shuffle(seed=inventory_hostname) }}
# => ['b','a','c']

Json数据查询过滤器

过滤器「json_query」,用于从json数据变量中摘取出一部分数据:

例如,下面是一个完整的json格式的变量

domain_definition:
domain:
cluster:
- name: "cluster1"
- name: "cluster2"
server:
- name: "server11"
cluster: "cluster1"
port: ""
- name: "server12"
cluster: "cluster1"
port: ""
- name: "server21"
cluster: "cluster2"
port: ""
- name: "server22"
cluster: "cluster2"
port: ""
library:
- name: "lib1"
target: "cluster1"
- name: "lib2"

从这个变量中摘取出所有的「name」:

- name: "Display all cluster names"
debug:
var: item
loop: "{{ domain_definition | json_query('domain.cluster[*].name') }}"

摘取cluster1的port:

- name: "Display all ports from cluster1"
debug:
var: item
loop: "{{ domain_definition | json_query(server_name_cluster1_query) }}"
vars:
server_name_cluster1_query: "domain.server[?cluster=='cluster1'].port"

摘取cluster2的name和port:

- name: "Display all server ports and names from cluster1"
debug:
var: item
loop: "{{ domain_definition | json_query(server_name_cluster1_query) }}"
vars:
server_name_cluster1_query: "domain.server[?cluster=='cluster2'].{name: name, port: port}"

IP地址过滤器

过滤器「ipaddr」,用于测试是否为IP地址格式:

{{ myvar | ipaddr }}

「ipaddr」过滤器也可以用于摘取出一个IP地址的指定信息:

例如,从一个CIDR摘取出IP地址信息:

{{ '192.0.2.1/24' | ipaddr('address') }}

输出结果为:

"msg": "192.0.2.1"

过滤器「ipv4」「ipv6」,用于检测ipv4和ipv6协议的IP地址:

{{ myvar | ipv4 }}
{{ myvar | ipv6 }}

哈希值过滤器

过滤器「hash」,用于获取字符串的hash值。

获取字符串的sha1哈希值:

{{ 'test1' | hash('sha1') }}

获取字符串的md5哈希值:

{{ 'test2' | hash('blowfish') }}

过滤器「checksum」,用于获取字符串的checksum:

{{ 'test2' | checksum }}

过滤器「password_hash」,用于获取一个密码的哈希值。

获取sha512密码哈希值,结果随机:

{{ 'passwordsaresecret' | password_hash('sha512') }}

获取sha256密码哈希值,并加盐处理,结果满足幂等性:

{{ 'secretpassword' | password_hash('sha256', 'mysecretsalt') }}

根据主机名获取一个满足幂等原则的sha256密码,写法如下:

{{ 'secretpassword' | password_hash('sha512',  | random(seed=inventory_hostname) | string) }}

一些hash类型也允许提供「rounds」参数:

{{ 'secretpassword' | password_hash('sha256', 'mysecretsalt', rounds=) }}

注:关于哈希加盐和rounds请自行Google。

操作字典元素过滤器

过滤器「combine」,用于合并字典数据。

默认情况下,不仅两个字典会被合并,字典数据也会被后面字典数据覆盖:

{{ {'a':, 'b':} | combine({'b':, 'c':}) }}

结果为:

{'a':, 'b':, 'c':}

如果字典类型是多层全套字典,我们可以添加「resursive=True」参数进行内层字典融合:

{{ {'a':{'foo':, 'bar':}, 'b':} | combine({'a':{'bar':, 'baz':}}, recursive=True) }}

结果为:

{'a':{'foo':, 'bar':, 'baz':}, 'b':}

多个字典递归融合:

{{ a | combine(b, c, d) }}

上述示例中,字典「d」会字典「c」进行合并与元素的覆盖,合并结果与字典「b」进行合并于覆盖,合并结果再与字典「a」进行合并与覆盖,返回最后的字典数据。

注:combine过滤器与ansible.cfg的「hash_behaviour」参数无关,即使「hash_behaviour」设置为了「replace」,在「combine」过滤器里依然会使用merge的方式进行融合。

参数提取过滤器

过滤器「map」,根据指定条件提取出列表或字典内的数据。

{{ [,] | map('extract', ['x','y','z']) | list }}
{{ ['x','y'] | map('extract', {'x': , 'y': }) | list }}

输出结果为:

['x', 'z']
[, ]

「map」还可以实现更加复杂的提取工作:

假设我想提取出主机组「nodes」下三个主机的「ansible_architecture」fact变量值,可以这样写:

{{ groups['nodes'] | map ('extract',hostvars,['ansible_architecture']) | list }}

输出结果为:

    "msg": [
"x86_64",
"x86_64",
"x86_64"
]

同理,如果我想查询三个节点的ip地址放到一个列表内,可以这样写:

{{ groups['nodes'] | map ('extract',hostvars,['ansible_default_ipv4','address']) | list }}

输出结果为:

    "msg": [
"10.211.55.7",
"10.211.55.9",
"10.211.55.8"
]

上面两个示例用一个比较简易的表达式表示如下,如果不理解可以当公式记住:

{{ ['a'] | map('extract', b, ['x','y']) | list }}

则会获取到b['a']['x']['y']的参数结果。

注释过滤器

过滤器「comment」,可以实现注释字符串的功能,默认为「#」注释。

{{ "Plain style (default)" | comment }}

结果为:

#
# Plain style (default)
#

我们也可以为 C (//...), C block (/*...*/), Erlang (%...) 和XML (<!--...-->)做注释,分别为:

{{ "C style" | comment('c') }}
{{ "C block style" | comment('cblock') }}
{{ "Erlang style" | comment('erlang') }}
{{ "XML style" | comment('xml') }}

使用「decoration」参数可以人为指定注释符号:

{{ "My Special Case" | comment(decoration="! ") }}

输出结果为:

!
! My Special Case
!

为了美观,我们也可以定制格式:

{{ "Custom style" | comment('plain', prefix='#######\n#', postfix='#\n#######\n   ###\n    #') }}

输出结果为:

#######
#
# Custom style
#
#######
###
#

「comment」也可以传递变量,例如「ansible_managed」变量为:

[defaults]
ansible_managed = This file is managed by Ansible.%n
template: {file}
date: %Y-%m-%d %H:%M:%S
user: {uid}
host: {host}

通过表达式:

{{ ansible_managed | comment }}

转化为:

#
# This file is managed by Ansible.
#
# template: /home/ansible/env/dev/ansible_managed/roles/role1/templates/test.j2
# date: -- ::
# user: ansible
# host: myhost
#

解析url过滤器

过滤器「urlsplit」,用于分解一个url链接,取出我们需要的字段,直接上官网示例:

{{ "http://user:password@www.acme.com:9000/dir/index.html?query=term#fragment" | urlsplit('hostname') }}
# => 'www.acme.com' {{ "http://user:password@www.acme.com:9000/dir/index.html?query=term#fragment" | urlsplit('netloc') }}
# => 'user:password@www.acme.com:9000' {{ "http://user:password@www.acme.com:9000/dir/index.html?query=term#fragment" | urlsplit('username') }}
# => 'user' {{ "http://user:password@www.acme.com:9000/dir/index.html?query=term#fragment" | urlsplit('password') }}
# => 'password' {{ "http://user:password@www.acme.com:9000/dir/index.html?query=term#fragment" | urlsplit('path') }}
# => '/dir/index.html' {{ "http://user:password@www.acme.com:9000/dir/index.html?query=term#fragment" | urlsplit('port') }}
# => '' {{ "http://user:password@www.acme.com:9000/dir/index.html?query=term#fragment" | urlsplit('scheme') }}
# => 'http' {{ "http://user:password@www.acme.com:9000/dir/index.html?query=term#fragment" | urlsplit('query') }}
# => 'query=term' {{ "http://user:password@www.acme.com:9000/dir/index.html?query=term#fragment" | urlsplit('fragment') }}
# => 'fragment' {{ "http://user:password@www.acme.com:9000/dir/index.html?query=term#fragment" | urlsplit }}
# =>
# {
# "fragment": "fragment",
# "hostname": "www.acme.com",
# "netloc": "user:password@www.acme.com:9000",
# "password": "password",
# "path": "/dir/index.html",
# "port": ,
# "query": "query=term",
# "scheme": "http",
# "username": "user"
# }

正则过滤器

过滤器「regex_search」,用于对一个字符串的正则匹配查找

# search for "foo" in "foobar"
{{ 'foobar' | regex_search('(foo)') }} # will return empty if it cannot find a match
{{ 'ansible' | regex_search('(foobar)') }} # case insensitive search in multiline mode
{{ 'foo\nBAR' | regex_search("^bar", multiline=True, ignorecase=True) }}

过滤器「regex_findall」,用于对所有事件进行查找:

# Return a list of all IPv4 addresses in the string
{{ 'Some DNS servers are 8.8.8.8 and 8.8.4.4' | regex_findall('\\b(?:[0-9]{1,3}\\.){3}[0-9]{1,3}\\b') }}

过滤器「regex_replace」,用于对一个字符串进行文本替换:

# convert "ansible" to "able"
{{ 'ansible' | regex_replace('^a.*i(.*)$', 'a\\1') }} # convert "foobar" to "bar"
{{ 'foobar' | regex_replace('^f.*o(.*)$', '\\1') }} # convert "localhost:80" to "localhost, 80" using named groups
{{ 'localhost:80' | regex_replace('^(?P<host>.+):(?P<port>\\d+)$', '\\g<host>, \\g<port>') }} # convert "localhost:80" to "localhost"
{{ 'localhost:80' | regex_replace(':80') }} # add "https://" prefix to each item in a list
{{ hosts | map('regex_replace', '^(.*)$', 'https://\\1') | list }}

过滤器「regex_escape」,用于转义特殊字符串:

# convert '^f.*o(.*)$' to '\^f\.\*o\(\.\*\)\$'
{{ '^f.*o(.*)$' | regex_escape() }}

其他过滤器

过滤器「quote」,给字符串添加引号,在shell模块内使用

- shell: echo {{ string_value | quote }}

过滤器「ternary」,根据前面语句的真与假选择一个字符串

{{ (name == "John") | ternary('Mr','Ms') }}

上面示例表示:如果变量「name」的值为「John」则表达式返回字符串「Mr」,否则返回字符串「Ms」。

过滤器「join」,将列表转换成字符串,可以指定连接符

{{ list | join(" ") }}

过滤器「basename」,获取一个文件的绝对路径,例如将「foo.txt」转换为「/etc/asdf/foo.txt」

{{ path | basename }}

过滤器「dirname」,获取一个文件或目录的上级目录

{{ path | dirname }}

例如:

「/etc/httpd/conf」将获取到「/etc/httpd」

「/etc/httpd/conf/」将获取到「/etc/httpd/conf」

「/etc/httpd/conf/httpd.conf」将获取到「/etc/httpd/conf」

过滤器「realpath」,获取一个链接文件的真实文件路径,默认是绝对路径

{{ path | realpath }}

获取「/etc」的相对路径

{{ path | relpath('/etc') }}

过滤器「splittext」,拆分字符串,将文件的位置提取出来作为一个单独的元素

# with path == 'nginx.conf' the return would be ('nginx', '.conf')
{{ path | splitext }}

过滤器「b64decode」「b64encode」,Base64编码与解码

{{ encoded | b64decode }}
{{ decoded | b64encode }}

过滤器「to_uuid」,根据一个字符串生成一个UUID

{{ hostname | to_uuid }}

过滤器「map」的另一个用法

# get a comma-separated list of the mount points (e.g. "/,/mnt/stuff") on a host
{{ ansible_mounts | map(attribute='mount') | join(',') }}

过滤器「to_datetime」,获取到的是日期对象

# Get total amount of seconds between two dates. Default date format is %Y-%m-%d %H:%M:%S but you can pass your own format
{{ (("2016-08-14 20:00:12" | to_datetime) - ("2015-12-25" | to_datetime('%Y-%m-%d'))).total_seconds() }} # Get remaining seconds after delta has been calculated. NOTE: This does NOT convert years, days, hours, etc to seconds. For that, use total_seconds()
{{ (("2016-08-14 20:00:12" | to_datetime) - ("2016-08-14 18:00:00" | to_datetime)).seconds }}
# This expression evaluates to "" and not "". Delta is hours, seconds # get amount of days between two dates. This returns only number of days and discards remaining hours, minutes, and seconds
{{ (("2016-08-14 20:00:12" | to_datetime) - ("2015-12-25" | to_datetime('%Y-%m-%d'))).days }}

格式化时间数据

# Display year-month-day
{{ '%Y-%m-%d' | strftime }} # Display hour:min:sec
{{ '%H:%M:%S' | strftime }} # Use ansible_date_time.epoch fact
{{ '%Y-%m-%d %H:%M:%S' | strftime(ansible_date_time.epoch) }} # Use arbitrary epoch value
{{ '%Y-%m-%d' | strftime() }} # => --
{{ '%Y-%m-%d' | strftime() }} # => --

过滤器「type_debug」,用于debug出数据类型

{{ myvar | type_debug }}

本节应该掌握的技能

  • 掌握Jinja2模版的使用分类和优点
  • 熟悉本文提到的过滤器,最少记住大概功能
  • 掌握在playbook和模版文件中使用过滤器的方法

参考链接

  • https://docs.ansible.com/ansible/latest/user_guide/playbooks_templating.html
  • https://docs.ansible.com/ansible/latest/user_guide/playbooks_filters.html

欢迎大家关注我的公众号:

ansible基础-Jinja2模版 | 过滤器