Фильтры

• Фильтры для форматирования данных
• Принудительное определение переменных
• Установление значений по умолчанию для неопределенных переменных
• Исключение параметров
• Фильтры для списков
• Фильтры теории множеств
• Фильтр случайных чисел
• Фильтр перемешивания
• Математические
• Фильтр запросов к JSON
• Фильтр IP-адресов
• Фильтры командной строки сетевых устройств
• Фильтры хеширования
• Объединение словарей/хешей
• Извлечение значений из контейнеров
• Фильтр комментариев
• Фильтр разделения URL
• Фильтры регулярных выражений
• Другие полезные фильтры
• Фильтры комбинирования
• Фильтры отладки

Фильтры в Ansible взяты из Jinja2 и используются для преобразования данных внутри выражения шаблона. Jinja2 поставляется со многими фильтрами. См. встроенные фильтры в официальной документации по шаблонам Jinja2.

Учитывайте, что шаблонизация происходит на контроллере Ansible, а не на целевом узле задачи, поэтому фильтры также выполняются на контроллере, так как они обрабатывают локальные данные.

Помимо тех, которые предоставляет Jinja2, Ansible поставляется со своими собственными и позволяет пользователям добавлять свои собственные пользовательские фильтры.

Фильтры для форматирования данных

Следующие фильтры примут структуру данных в шаблоне и отобразят её в немного другом формате. Это иногда бывает полезно для отладки:

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

Для удобочитаемого вывода вы можете использовать:

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

Также можно изменить отступы (новая функция с версии 2.2):

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

В качестве альтернативы, вы можете читать некоторые уже отформатированные данные:

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

например:

tasks:
  - shell: cat /some/path/to/file.json
    register: result

  - set_fact: myvar="{{ result.stdout | from_json }}"

Принудительное определение переменных

По умолчанию в ansible и ansible.cfg происходит ошибка, если переменные не определены, но вы можете отключить это поведение.

Это позволяет явно проверить это, отключив эту функцию:

{{ variable | mandatory }}

Значение переменной будет использоваться как есть, но оценка шаблона вызовет ошибку, если она не определена.

Установление значений по умолчанию для неопределенных переменных

Jinja2 предоставляет полезный фильтр ‘default’, который часто является лучшим подходом, чем ошибка, если переменная не определена:

{{ some_variable | default(5) }}

В приведенном выше примере, если переменная ‘some_variable’ не определена, используемое значение будет 5, а не ошибка.

Исключение параметров

Начиная с Ansible 1.8, можно использовать фильтр default для исключения параметров модуля, используя специальную переменную omit:

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

Для первых двух файлов в списке режим по умолчанию будет определяться маской umask системы, так как параметр mode= не будет отправлен в модуль файла, в то время как последний файл получит опцию mode=0444.

Фильтры для списков

Все эти фильтры работают со списками.

Для получения минимального значения из списка чисел:

{{ list1 | min }}

Для получения максимального значения из списка чисел:

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

Фильтры теории множеств

Все эти функции возвращают уникальное множество из множеств или списков.

Для получения уникального множества из списка:

{{ list1 | unique }}

Для получения объединения двух списков:

{{ list1 | union(list2) }}

Для получения пересечения 2 списков (уникальный список всех элементов в обоих):

{{ list1 | intersect(list2) }}

Для получения разности 2 списков (элементы в 1, которые не существуют во 2):

{{ list1 | difference(list2) }}

Для получения симметричной разности 2 списков (элементы, уникальные для каждого списка):

{{ list1 | symmetric_difference(list2) }}

Фильтр случайных чисел

Этот фильтр может использоваться подобно стандартному фильтру Jinja2 random (возвращая случайный элемент из последовательности элементов), но также может генерировать случайное число в заданном диапазоне.

Для получения случайного элемента из списка:

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

Для получения случайного числа от 0 до заданного числа:

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

Получение случайного числа от 0 до 100 с шагом 10:

{{ 101 |random(step=10) }}
# => 70

Получение случайного числа от 1 до 100 с шагом 10:

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

Начиная с версии Ansible 2.3, также можно инициализировать генератор случайных чисел из значения. Таким образом, вы можете создавать случайные, но идемпотентные числа:

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

Фильтр перемешивания

Этот фильтр случайным образом перемешивает существующий список, давая каждый раз другой порядок.

Для получения случайного списка из существующего списка:

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

Начиная с версии Ansible 2.3, также можно перемешивать список идемпотентно. Все, что вам нужно, это значение.:

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

обратите внимание, что при использовании с элементом, который не является «списком», это ничто, иначе он всегда возвращает список

Математические

Получение логарифма (по умолчанию e):

{{ myvar | log }}

Получение логарифма по основанию 10:

{{ myvar | log(10) }}

Получение степени 2! (или 5):

{{ myvar | pow(2) }}
{{ myvar | pow(5) }}

Квадратный корень или 5-й:

{{ myvar | root }}
{{ myvar | root(5) }}

Обратите внимание, что Jinja2 уже предоставляет некоторые, такие как abs() и round().

Фильтр запросов к JSON

Иногда вы получаете сложную структуру данных в формате JSON, и вам нужно извлечь только небольшой набор данных в ней. Фильтр json_query позволяет запросить сложную структуру JSON и выполнить итерацию по ней с помощью структуры with_items.

Теперь давайте рассмотрим следующую структуру данных:

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"
              target: "cluster2"

Для извлечения всех кластеров из этой структуры можно использовать следующий запрос:

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

То же самое для всех имен серверов:

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

Этот пример показывает порты из cluster1:

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

В этом примере мы получаем хеш-таблицу со всеми портами и именами кластера:

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

Фильтр IP-адресов

Для проверки, является ли строка допустимым IP-адресом:

{{ myvar | ipaddr }}

Вы также можете потребовать определенной версии протокола IP:

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

Фильтр IP-адресов также может использоваться для извлечения определенной информации из IP-адреса. Например, чтобы получить сам IP-адрес из CIDR, вы можете использовать:

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

Дополнительную информацию о фильтре ipaddr и полное руководство по использованию можно найти в фильтре ipaddr.

Фильтры командной строки сетевых устройств

Для преобразования вывода команды CLI сетевого устройства в структурированный JSON-вывод, используйте фильтр parse_cli:

{{ output | parse_cli('path/to/spec') }}

Фильтр parse_cli загрузит файл спецификаций и передаст вывод команды, вернув JSON-вывод. Файл спецификаций — это YAML-файл, который определяет, как парсить вывод CLI.

Файл спецификаций должен быть валидным отформатированным YAML. Он определяет, как обработать вывод командной строки и вернуть данные JSON. Ниже приведен пример валидного файла спецификаций, который будет анализировать вывод команды show vlan:

---
vars:
  vlan:
    vlan_id: "{{ item.vlan_id }}"
    name: "{{ item.name }}"
    enabled: "{{ item.state != 'act/lshut' }}"
    state: "{{ item.state }}"

keys:
  vlans:
    type: list
    value: "{{ vlan }}"
    items: "^(?P<vlan_id>\\d+)\\s+(?P<name>\\w+)\\s+(?P<state>active|act/lshut|suspended)"
  state_static:
    value: present

Файл спецификаций выше вернет структуру данных JSON, которая представляет собой список хешей с информацией о VLAN.

Ту же команду можно разобрать в хеш, используя директивы ключа и значения. Вот пример того, как разобрать вывод в значение хеша, используя ту же команду show vlan:

---
vars:
  vlan:
    key: "{{ item.vlan_id }}"
    values:
      vlan_id: "{{ item.vlan_id }}"
      name: "{{ item.name }}"
      enabled: "{{ item.state != 'act/lshut' }}"
      state: "{{ item.state }}"

keys:
  vlans:
    type: list
    value: "{{ vlan }}"
    items: "^(?P<vlan_id>\\d+)\\s+(?P<name>\\w+)\\s+(?P<state>active|act/lshut|suspended)"
  state_static:
    value: present

Еще один распространенный случай использования для парсинга команд CLI — разбить одну большую команду на блоки, которые можно обработать. Это можно сделать, используя директивы start_block и end_block для разбиения команды на блоки, которые можно обработать:

---
vars:
  interface:
    name: "{{ item[0].match[0] }}"
    state: "{{ item[1].state }}"
    mode: "{{ item[2].match[0] }}"

keys:
  interfaces:
    value: "{{ interface }}"
    start_block: "^Ethernet.*$"
    end_block: "^$"
    items:
      - "^(?P<name>Ethernet\\d\\/\\d*)"
      - "admin state is (?P<state>.+),"
      - "Port mode is (.+)"

Приведенный выше пример разобьёт вывод команды show interface на список хешей.

Фильтры сети также поддерживают парсинг вывода команды CLI с помощью библиотеки TextFSM. Чтобы разобрать вывод CLI с помощью TextFSM, используйте следующий фильтр:

{{ output | parse_cli_textfsm('path/to/fsm') }}

Для использования фильтра TextFSM необходимо установить библиотеку TextFSM.

Фильтры хеширования

Чтобы получить sha1 хеш строки:

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

Чтобы получить md5 хеш строки:

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

Получить контрольную сумму строки:

{{ 'test2'|checksum }}

Другие хеши (зависит от платформы):

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

Чтобы получить хеш пароля sha512 (случайная соль):

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

Чтобы получить хеш пароля sha256 с указанной солью:

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

Доступные типы хешей зависят от основной системы, на которой выполняется ansible, «hash» зависит от hashlib, password_hash зависит от passlib (http://passlib.readthedocs.io/en/stable/lib/passlib.hash.html).

Объединение хешей/словарей

Фильтр combine позволяет объединять хеши. Например, следующее переопределяет ключи в одном хеше:

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

Результирующий хеш будет:

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

Фильтр также принимает необязательный параметр recursive=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 и так далее.

Это поведение не зависит от значения параметра hash_behaviour в ansible.cfg.

Извлечение значений из контейнеров

Фильтр extract используется для отображения списка индексов в список значений из контейнера (хеш или массив):

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

Результаты приведенных выше выражений будут:

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

Фильтр может принимать другой аргумент:

{{ groups['x']|map('extract', hostvars, 'ec2_ip_address')|list }}

Это берет список хостов в группе «x», ищет их в hostvars, а затем ищет ec2_ip_address результата. Конечным результатом является список IP-адресов для хостов в группе «x».

Третий аргумент фильтра также может быть списком для рекурсивного поиска внутри контейнера:

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

Это вернет список, содержащий значение b[‘a’][‘x’][‘y’].

Фильтр комментариев

Фильтр comment позволяет форматировать текст выбранным стилем комментариев. Например, следующее:

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

выведет такой результат:

#
# Plain style (default)
#

Аналогичным образом можно применить стиль для C (//...), блока C (/*...*/), Erlang (%...) и XML (<!--...-->):

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

Также можно полностью настроить стиль комментариев:

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

Это создаст следующий вывод:

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

Фильтр также может быть применен к любой переменной Ansible. Например, чтобы сделать вывод переменной ansible_managed более удобочитаемым, можно изменить определение в файле ansible.cfg следующим образом:

[defaults]

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

а затем использовать переменную с фильтром comment:

{{ 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 извлекает фрагмент, имя хоста, netloc, пароль, путь, порт, запрос, схему и имя пользователя из URL. Без аргументов возвращает словарь всех полей:

{{ "http://user:password@www.acme.com:9000/dir/index.html?query=term#frament" | urlsplit('hostname') }}
# => 'www.acme.com'

{{ "http://user:password@www.acme.com:9000/dir/index.html?query=term#frament" | urlsplit('netloc') }}
# => 'user:password@www.acme.com:9000'

{{ "http://user:password@www.acme.com:9000/dir/index.html?query=term#frament" | urlsplit('username') }}
# => 'user'

{{ "http://user:password@www.acme.com:9000/dir/index.html?query=term#frament" | urlsplit('password') }}
# => 'password'

{{ "http://user:password@www.acme.com:9000/dir/index.html?query=term#frament" | urlsplit('path') }}
# => '/dir/index.html'

{{ "http://user:password@www.acme.com:9000/dir/index.html?query=term#frament" | urlsplit('port') }}
# => '9000'

{{ "http://user:password@www.acme.com:9000/dir/index.html?query=term#frament" | urlsplit('scheme') }}
# => 'http'

{{ "http://user:password@www.acme.com:9000/dir/index.html?query=term#frament" | urlsplit('query') }}
# => 'query=term'

{{ "http://user:password@www.acme.com:9000/dir/index.html?query=term#frament" | urlsplit('fragment') }}
# => 'fragment'

{{ "http://user:password@www.acme.com:9000/dir/index.html?query=term#frament" | 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)') }}

Для поиска всех вхождений совпадений регулярного выражения используйте фильтр «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') }}

Для экранирования специальных символов в регулярном выражении используйте фильтр «regex_escape»:

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

Другие полезные фильтры

Чтобы добавить кавычки для использования в оболочке:

- shell: echo {{ string_value | quote }}

Для использования одного значения при истинности и другого при ложности (ново в версии 1.9):

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

Для конкатенации списка в строку:

{{ list | join(" ") }}

Для получения последней части имени файла, например, 'foo.txt' из '/etc/asdf/foo.txt':

{{ path | basename }}

Для получения последней части имени файла в стиле Windows (ново в версии 2.0):

{{ path | win_basename }}

Для разделения буквенного обозначения диска Windows от остальной части пути к файлу (ново в версии 2.0):

{{ path | win_splitdrive }}

Для получения только буквенного обозначения диска Windows:

{{ path | win_splitdrive | first }}

Для получения остальной части пути без буквенного обозначения диска:

{{ path | win_splitdrive | last }}

Для получения каталога из пути:

{{ path | dirname }}

Для получения каталога из пути в стиле Windows (ново в версии 2.0):

{{ path | win_dirname }}

Для расширения пути, содержащего символ тильды (~) (ново в версии 1.5):

{{ path | expanduser }}

Для получения реального пути ссылки (ново в версии 1.8):

{{ path | realpath }}

Для получения относительного пути ссылки от начальной точки (ново в версии 1.7):

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

Для получения корня и расширения пути или имени файла (ново в версии 2.0):

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

Для работы со строками, закодированными в Base64:

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

Для создания UUID из строки (ново в версии 1.9):

{{ hostname | to_uuid }}

Для приведения значений к определенным типам, например, когда вы вводите строку как «True» из vars_prompt, а система не распознает её как логическое значение:

- debug: msg=test
  when: some_string_value | bool

Для использования одного атрибута из каждого элемента в списке сложных переменных используйте фильтр «map» (см. документацию Jinja2 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, (ново в версии 2.2):

# get amount of seconds between two dates, default date format is %Y-%m-%d %H:%M:%S but you can pass your own one
{{ (("2016-08-14 20:00:12"|to_datetime) - ("2015-12-25"|to_datetime('%Y-%m-%d'))).seconds  }}

Фильтры комбинаций

Этот набор фильтров возвращает список объединённых списков. Для получения перестановок списка:

- name: give me largest permutations (order matters)
  debug: msg="{{ [1,2,3,4,5]|permutations|list }}"

- name: give me permutations of sets of three
  debug: msg="{{ [1,2,3,4,5]|permutations(3)|list }}"

Комбинации всегда требуют установленного размера:

- name: give me combinations for sets of two
  debug: msg="{{ [1,2,3,4,5]|combinations(2)|list }}"

Для получения списка, объединяющего элементы других списков, используйте zip:

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

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

Для полного перебора всех списков используйте zip_longest:

- name: give me longest combo of three lists , fill with X
  debug: msg="{{ [1,2,3]|zip_longest(['a','b','c','d','e','f'], [21, 22, 23], fillvalue='X')|list }}"

Для форматирования даты с помощью строки (как с командой оболочки date), используйте фильтр «strftime»:

# 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 для отображения базового типа Python переменной. Это может быть полезно в отладке в ситуациях, когда вам нужно знать точный тип переменной:

{{ myvar | type_debug }}

Некоторые полезные фильтры обычно добавляются с каждым новым релизом Ansible. Документация по разработке показывает, как расширить фильтры Ansible, написав собственные плагины, но, как правило, мы рекомендуем добавлять новые фильтры в ядро, чтобы все могли ими воспользоваться.