ansible基础-Jinja2模版 | 过滤器

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=2) }}
{{ some_variable | to_nice_yaml(indent=8) }}

过滤器「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(5) }}

另外，如果我们想将变量参数是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: "0444"

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

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

列表过滤器

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

{{ list1 | min }}

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

{{ [3, 4, 2] | max }}

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

{{ [3, [4, 2] ] | flatten }}

转换结果为：

[3, 4, 2 ]

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

{{ [3, [4, [2]] ] | flatten(levels=1) }}

只转换一级的列表元素，结果为：

[3, 4, [2] ]

过滤器「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": [
        [
            1,
            "a"
        ],
        [
            2,
            "b"
        ],
        [
            3,
            "c"
        ],
        [
            4,
            "d"
        ],
        [
            5,
            "e"
        ]
    ]

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

{{ [1,2,3] | zip_longest(['a','b','c','d','e','f'], [21, 22, 23], [100,200,300],fillvalue='X') | list }}

转换结果为：

 "msg": [
        [
            1,
            "a",
            21,
            100
        ],
        [
            2,
            "b",
            22,
            200
        ],
        [
            3,
            "c",
            23,
            300
        ],
        [
            "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:

{{ 101 | random(1, 10) }}
# => 31
{{ 101 | random(start=1, step=10) }}
# => 51

添加「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: "8080"
            - name: "server12"
              cluster: "cluster1"
              port: "8090"
            - name: "server21"
              cluster: "cluster2"
              port: "9080"
            - name: "server22"
              cluster: "cluster2"
              port: "9090"
        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', 65534 | random(seed=inventory_hostname) | string) }}

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

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

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

操作字典元素过滤器

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

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

{{ {'a':1, 'b':2} | combine({'b':3, 'c':4}) }}

结果为：

{'a':1, 'b':3, 'c':4}

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

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

结果为：

{'a':{'foo':1, 'bar':3, 'baz':4}, 'b':2}

多个字典递归融合：

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

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

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

参数提取过滤器

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

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

输出结果为：

['x', 'z']
[42, 31]

「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='#######
#', postfix='#
#######
   ###
    #') }}

输出结果为：

#######
#
# 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: 2015-09-10 11:02:58
# 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') }}
# => '9000'

{{ "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": 9000,
#       "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
BAR' | 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」

1{{ 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 "12" and not "132". Delta is 2 hours, 12 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(0) }}          # => 1970-01-01
{{ '%Y-%m-%d' | strftime(1441357287) }} # => 2015-09-04

过滤器「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

 

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