Использование фильтров для обработки данных

Указание значений по умолчанию

Вы можете указать значения по умолчанию для переменных непосредственно в ваших шаблонах, используя фильтр Jinja2 «default». Это часто лучший подход, чем отказ при неопределении переменной:

{{ some_variable | default(5) }}

В приведенном выше примере, если переменная «some_variable» не определена, Ansible использует значение по умолчанию 5, вместо того, чтобы генерировать ошибку «неопределенная переменная» и завершиться сбоем. Если вы работаете в рамках роли, вы также можете добавить значения по умолчанию для роли, чтобы определить значения по умолчанию для переменных в вашей роли. Чтобы узнать больше о значениях по умолчанию для ролей, см. Структуру каталога ролей.

Начиная с версии 2.8, попытка доступа к атрибуту неопределенного значения в Jinja вернет другое неопределенное значение, а не выбросит ошибку немедленно. Это означает, что теперь вы можете просто использовать значение по умолчанию с данными вложенной структуры данных (иными словами, {{ foo.bar.baz | default('DEFAULT') }}), когда вы не знаете, определены ли промежуточные значения.

Если вы хотите использовать значение по умолчанию, когда переменные имеют значение false или пустую строку, вам нужно установить второй параметр на true:

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

Делаем переменные необязательными

По умолчанию Ansible требует значений для всех переменных в шаблонизированном выражении. Однако вы можете сделать определенные переменные модуля необязательными. Например, вы можете использовать системное значение по умолчанию для некоторых элементов и контролировать значение для других. Чтобы сделать переменную модуля необязательной, установите значение по умолчанию для специальной переменной omit:

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

В этом примере режим по умолчанию для файлов /tmp/foo и /tmp/bar определяется системной маской. Ansible не отправляет значение для mode. Только третий файл, /tmp/baz, получает параметр mode=0444.

Определение обязательных значений

Если вы настроите Ansible на игнорирование неопределенных переменных, вы можете захотеть определить некоторые значения как обязательные. По умолчанию Ansible завершается ошибкой, если переменная в вашем плейбуке или команде неопределена. Вы можете настроить Ansible на разрешение неопределенных переменных, установив DEFAULT_UNDEFINED_VAR_BEHAVIOR на false. В этом случае вы можете потребовать определения некоторых переменных. Вы можете сделать это с помощью:

{{ variable | mandatory }}

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

Удобный способ потребовать переопределения переменной — присвоить ей неопределенное значение с помощью функции undef().

galaxy_url: "https://galaxy.ansible.com"
galaxy_api_key: "{{ undef(hint='You must specify your Galaxy API key') }}"

Определение типа данных

Если вы не уверены в базовом типе Python переменной, вы можете использовать фильтр ansible.builtin.type_debug для его отображения. Это полезно при отладке, когда вам нужен конкретный тип переменной:

{{ myvar | type_debug }}

Следует отметить, что, хотя этот фильтр может показаться полезным для проверки того, что у вас есть нужный тип данных в переменной, вы часто предпочитаете тесты типа, которые позволят вам проверить конкретные типы данных.

Преобразование строк в списки

Используйте фильтр ansible.builtin.split для преобразования строки, разделитель которой является символом или строкой, в список элементов, подходящий для циклов. Например, если вы хотите разбить строковую переменную fruits по запятым, вы можете использовать:

{{ fruits | split(',') }}

Данные строки (до применения фильтра ansible.builtin.split):

fruits: apple,banana,orange

Данные списка (после применения фильтра ansible.builtin.split):

- apple
- banana
- orange

Преобразование словарей в списки

Используйте фильтр ansible.builtin.dict2items для преобразования словаря в список элементов, подходящий для циклов:

{{ dict | dict2items }}

Данные словаря (до применения фильтра ansible.builtin.dict2items):

tags:
  Application: payment
  Environment: dev

Данные списка (после применения фильтра ansible.builtin.dict2items):

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

Фильтр ansible.builtin.dict2items является обратным фильтру ansible.builtin.items2dict.

Если вы хотите настроить имена ключей, фильтр ansible.builtin.dict2items принимает 2 ключевых аргумента. Передайте аргументы key_name и value_name для настройки имён ключей в выходном списке:

{{ files | dict2items(key_name='file', value_name='path') }}

Данные словаря (до применения фильтра ansible.builtin.dict2items):

files:
  users: /etc/passwd
  groups: /etc/group

Данные списка (после применения фильтра ansible.builtin.dict2items):

- file: users
  path: /etc/passwd
- file: groups
  path: /etc/group

Преобразование списков в словари

Используйте фильтр ansible.builtin.items2dict для преобразования списка в словарь, отображая содержимое в key: value пары:

{{ tags | items2dict }}

Данные списка (до применения фильтра ansible.builtin.items2dict):

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

Данные словаря (после применения фильтра ansible.builtin.items2dict):

Application: payment
Environment: dev

Фильтр ansible.builtin.items2dict является обратным фильтру ansible.builtin.dict2items.

Не все списки используют key для обозначения ключей и value для обозначения значений. Например:

fruits:
  - fruit: apple
    color: red
  - fruit: pear
    color: yellow
  - fruit: grapefruit
    color: yellow

В этом примере необходимо передать аргументы key_name и value_name для настройки преобразования. Например:

{{ fruits | items2dict(key_name='fruit', value_name='color') }}

Если вы не передадите эти аргументы или не передадите правильные значения для вашего списка, вы увидите KeyError: key или KeyError: my_typo.

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

Вы можете преобразовывать значения в определенные типы. Например, если вы ожидаете ввод «True» от vars_prompt и хотите, чтобы Ansible распознал его как булево значение, а не строку:

- ansible.builtin.debug:
     msg: test
  when: some_string_value | bool

Если вы хотите выполнить математическое сравнение с фактом и хотите, чтобы Ansible распознал его как целое число, а не строку:

- shell: echo "only on Red Hat 6, derivatives, and later"
  when: ansible_facts['os_family'] == "RedHat" and ansible_facts['lsb']['major_release'] | int >= 6

Фильтр to_json и поддержка Unicode

По умолчанию ansible.builtin.to_json и ansible.builtin.to_nice_json преобразуют полученные данные в ASCII, поэтому:

{{ 'München'| to_json }}

вернёт:

'M\u00fcnchen'

Чтобы сохранить символы Unicode, передайте параметр ensure_ascii=False в фильтр:

{{ 'München'| to_json(ensure_ascii=False) }}

'München'

Для разбора строк YAML с несколькими документами предоставляется фильтр ansible.builtin.from_yaml_all. Фильтр ansible.builtin.from_yaml_all вернёт генератор распарсенных документов YAML.

например:

tasks:
  - name: Register a file content as a variable
    ansible.builtin.shell: cat /some/path/to/multidoc-file.yaml
    register: result

  - name: Print the transformed variable
    ansible.builtin.debug:
      msg: '{{ item }}'
    loop: '{{ result.stdout | from_yaml_all | list }}'

Объединение элементов из нескольких списков: zip и zip_longest

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

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

# => [[1, "a"], [2, "b"], [3, "c"], [4, "d"], [5, "e"], [6, "f"]]

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

# => [[1, "a"], [2, "b"], [3, "c"]]

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

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

# => [[1, "a", 21], [2, "b", 22], [3, "c", 23], ["X", "d", "X"], ["X", "e", "X"], ["X", "f", "X"]]

Аналогично выводу фильтра ansible.builtin.items2dict, упомянутого выше, эти фильтры могут использоваться для построения dict:

{{ dict(keys_list | zip(values_list)) }}

Данные списка (до применения фильтра ansible.builtin.zip):

keys_list:
  - one
  - two
values_list:
  - apple
  - orange

Данные словаря (после применения фильтра ansible.builtin.zip):

one: apple
two: orange

Объединение объектов и подэлементов

Фильтр ansible.builtin.subelements производит произведение объекта и значений подэлементов этого объекта, аналогично поиску ansible.builtin.subelements. Это позволяет указать отдельные подэлементы для использования в шаблоне. Например, это выражение:

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

Данные до применения фильтра ansible.builtin.subelements:

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

Данные после применения фильтра ansible.builtin.subelements:

-
  - 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

Вы можете использовать преобразованные данные с loop для итерации по одному и тому же подэлементу для нескольких объектов:

- name: Set authorized ssh key, extracting just that data from 'users'
  ansible.posix.authorized_key:
    user: "{{ item.0.name }}"
    key: "{{ lookup('file', item.1) }}"
  loop: "{{ users | subelements('authorized') }}"

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

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

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

Получившийся хеш будет:

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

Фильтр также может принимать несколько аргументов для объединения:

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

В этом случае ключи в d переопределят ключи в c, которые, в свою очередь, переопределят ключи в b, и так далее.

Фильтр также принимает два необязательных параметра: recursive и list_merge.

recursive

Это булево значение, по умолчанию равное False. Необходимо ли фильтру ansible.builtin.combine рекурсивно объединять вложенные хеши. Примечание: Это не зависит от значения параметра hash_behaviour в ansible.cfg.

list_merge

Это строка, возможные значения которой replace (по умолчанию), keep, append, prepend, append_rp или prepend_rp. Он изменяет поведение фильтра ansible.builtin.combine при объединении хешей, содержащих массивы/списки.

default:
  a:
    x: default
    y: default
  b: default
  c: default
patch:
  a:
    y: patch
    z: patch
  b: patch

Если recursive=False (по умолчанию), вложенные хеши не объединяются:

{{ default | combine(patch) }}

Это приведет к:

a:
  y: patch
  z: patch
b: patch
c: default

Если recursive=True, происходит рекурсивное объединение ключей вложенных хешей:

{{ default | combine(patch, recursive=True) }}

Это приведет к:

a:
  x: default
  y: patch
  z: patch
b: patch
c: default

Если list_merge='replace' (по умолчанию), массивы из правого хеша «заменят» массивы в левом хеше:

default:
  a:
    - default
patch:
  a:
    - patch

{{ default | combine(patch) }}

Это приведет к:

a:
  - patch

Если list_merge='keep', массивы из левого хеша сохранятся:

{{ default | combine(patch, list_merge='keep') }}

Это приведет к:

a:
  - default

Если list_merge='append', массивы из правого хеша будут добавлены к массивам из левого хеша:

{{ default | combine(patch, list_merge='append') }}

Это приведет к:

a:
  - default
  - patch

Если list_merge='prepend', массивы из правого хеша будут добавлены в начало массивов из левого хеша:

{{ default | combine(patch, list_merge='prepend') }}

Это приведет к:

a:
  - patch
  - default

Если list_merge='append_rp', массивы из правого хеша будут добавлены к массивам из левого хеша. Элементы массивов в левом хеше, которые также присутствуют в соответствующем массиве правого хеша, будут удалены («rp» означает «удалить присутствующий»). Повторяющиеся элементы, которые не присутствуют в обоих хешах, сохраняются:

default:
  a:
    - 1
    - 1
    - 2
    - 3
patch:
  a:
    - 3
    - 4
    - 5
    - 5

{{ default | combine(patch, list_merge='append_rp') }}

Это приведет к:

a:
  - 1
  - 1
  - 2
  - 3
  - 4
  - 5
  - 5

Если list_merge='prepend_rp', поведение аналогично предыдущему, но элементы массивов из правого хеша добавляются в начало:

{{ default | combine(patch, list_merge='prepend_rp') }}

Это приведет к:

a:
  - 3
  - 4
  - 5
  - 5
  - 1
  - 1
  - 2

recursive и list_merge могут быть использованы вместе:

default:
  a:
    a':
      x: default_value
      y: default_value
      list:
        - default_value
  b:
    - 1
    - 1
    - 2
    - 3
patch:
  a:
    a':
      y: patch_value
      z: patch_value
      list:
        - patch_value
  b:
    - 3
    - 4
    - 4
    - key: value

{{ default | combine(patch, recursive=True, list_merge='append_rp') }}

Это приведет к:

a:
  a':
    x: default_value
    y: patch_value
    z: patch_value
    list:
      - default_value
      - patch_value
b:
  - 1
  - 1
  - 2
  - 3
  - 4
  - 4
  - key: value

Выбор значений из массивов или хеш-таблиц

Фильтр 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’].

Объединение списков

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

- name: Give me the largest permutations (order matters)
  ansible.builtin.debug:
    msg: "{{ [1,2,3,4,5] | ansible.builtin.permutations | list }}"

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

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

- name: Generate multiple hostnames
  ansible.builtin.debug:
    msg: "{{ ['foo', 'bar'] | product(['com']) | map('join', '.') | join(',') }}"

{ "msg": "foo.com,bar.com" }

Выбор данных JSON: запросы JSON

Для выбора одного элемента или подмножества данных из сложной структуры данных в формате JSON (например, фактов Ansible) используйте фильтр community.general.json_query. Фильтр community.general.json_query позволяет вам запросить сложную структуру JSON и перебирать её с помощью цикла.

Рассмотрим эту структуру данных:

{
    "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
  ansible.builtin.debug:
    var: item
  loop: "{{ domain_definition | community.general.json_query('domain.cluster[*].name') }}"

Чтобы извлечь все имена серверов:

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

Чтобы извлечь порты из кластера cluster1:

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

Чтобы вывести порты из cluster1 в виде строки, разделенной запятыми:

- name: Display all ports from cluster1 as a string
  ansible.builtin.debug:
    msg: "{{ domain_definition | community.general.json_query('domain.server[?cluster==`cluster1`].port') | join(', ') }}"

Вы можете использовать YAML экранирование одиночных кавычек:

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

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

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

Чтобы извлечь порты из всех кластеров, имена которых начинаются с «server1»:

- name: Display ports from all clusters with the name starting with 'server1'
  ansible.builtin.debug:
    msg: "{{ domain_definition | to_json | from_json | community.general.json_query(server_name_query) }}"
  vars:
    server_name_query: "domain.server[?starts_with(name,'server1')].port"

Чтобы извлечь порты из всех кластеров, имена которых содержат «server1»:

- name: Display ports from all clusters with the name containing 'server1'
  ansible.builtin.debug:
    msg: "{{ domain_definition | to_json | from_json | community.general.json_query(server_name_query) }}"
  vars:
    server_name_query: "domain.server[?contains(name,'server1')].port"

Случайные MAC-адреса

Этот фильтр может быть использован для генерации случайного MAC-адреса из строкового префикса.

Чтобы получить случайный MAC-адрес из строкового префикса, начинающегося с «52:54:00»:

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

Обратите внимание, что если что-то не так со строкой префикса, фильтр выдаст ошибку.

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

"{{ '52:54:00' | community.general.random_mac(seed=inventory_hostname) }}"

Случайные элементы или числа

Фильтр ansible.builtin.random в Ansible является расширением стандартного фильтра 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

Вы можете инициализировать генератор случайных чисел из семян, чтобы создавать случайные, но идемпотентные числа:

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

Перемешивание списка

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

Чтобы получить случайный список из существующего списка:

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

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

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

Фильтр shuffle возвращает список, когда это возможно. Если вы используете его с элементом, не являющимся «списком», фильтр ничего не делает.

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

Чтобы проверить, является ли строка валидным IP-адресом:

{{ myvar | ansible.utils.ipaddr }}

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

{{ myvar | ansible.utils.ipv4 }}
{{ myvar | ansible.utils.ipv6 }}

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

{{ '192.0.2.1/24' | ansible.utils.ipaddr('address') }}
# => 192.0.2.1

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

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

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

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

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

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

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

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

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

Ту же команду можно проанализировать в хеш, используя директивы key и values. Вот пример того, как проанализировать вывод в значение хеша, используя ту же команду 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:
    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. Чтобы проанализировать вывод командной строки с помощью TextFSM, используйте следующий фильтр:

{{ output.stdout[0] | ansible.netcommon.parse_cli_textfsm('path/to/fsm') }}

Использование фильтра TextFSM требует установки библиотеки TextFSM.

Фильтры сетевого XML

Для преобразования XML-вывода команды сетевого устройства в структурированный вывод JSON используйте фильтр ansible.netcommon.parse_xml:

{{ output | ansible.netcommon.parse_xml('path/to/spec') }}

Фильтр ansible.netcommon.parse_xml загрузит файл спецификации и пропустит вывод команды, отформатированный как JSON.

Файл спецификации должен быть валидным файлом YAML. Он определяет, как анализировать XML-вывод и возвращать данные JSON.

Ниже приведен пример валидного файла спецификации, который будет анализировать вывод команды show vlan | display xml.

---
vars:
  vlan:
    vlan_id: "{{ item.vlan_id }}"
    name: "{{ item.name }}"
    desc: "{{ item.desc }}"
    enabled: "{{ item.state.get('inactive') != 'inactive' }}"
    state: "{% if item.state.get('inactive') == 'inactive'%} inactive {% else %} active {% endif %}"

keys:
  vlans:
    value: "{{ vlan }}"
    top: configuration/vlans/vlan
    items:
      vlan_id: vlan-id
      name: name
      desc: description
      state: ".[@inactive='inactive']"

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

Ту же команду можно проанализировать в хеш, используя директивы key и values. Вот пример того, как проанализировать вывод в значение хеша, используя ту же команду show vlan | display xml.

---
vars:
  vlan:
    key: "{{ item.vlan_id }}"
    values:
        vlan_id: "{{ item.vlan_id }}"
        name: "{{ item.name }}"
        desc: "{{ item.desc }}"
        enabled: "{{ item.state.get('inactive') != 'inactive' }}"
        state: "{% if item.state.get('inactive') == 'inactive'%} inactive {% else %} active {% endif %}"

keys:
  vlans:
    value: "{{ vlan }}"
    top: configuration/vlans/vlan
    items:
      vlan_id: vlan-id
      name: name
      desc: description
      state: ".[@inactive='inactive']"

Значение top — XPath относительно корневого узла XML. В приведённом ниже примере XML-вывода значение top равно configuration/vlans/vlan, что является выражением XPath относительно корневого узла (<rpc-reply>). configuration в значении top — это самый внешний контейнерный узел, а vlan — самый внутренний контейнерный узел.

items — это словарь пар ключ-значение, которые отображают пользовательские имена на выражения XPath, выбирающие элементы. Выражение XPath относиться к значению XPath, содержащемуся в top. Например, vlan_id в файле спецификации — это пользовательское имя, а его значение vlan-id — это значение, относительное к XPath в top

Атрибуты тегов XML могут быть извлечены с помощью выражений XPath. Значение state в спецификации — это выражение XPath, используемое для получения атрибутов тега vlan в выходном XML:

<rpc-reply>
  <configuration>
    <vlans>
      <vlan inactive="inactive">
       <name>vlan-1</name>
       <vlan-id>200</vlan-id>
       <description>This is vlan-1</description>
      </vlan>
    </vlans>
  </configuration>
</rpc-reply>

Фильтры сетевой VLAN

Используйте фильтр ansible.netcommon.vlan_parser, чтобы преобразовать несортированный список целочисленных значений VLAN в отсортированный строковый список целых чисел в соответствии с правилами списков VLAN в стиле IOS. Этот список имеет следующие свойства:

• VLANs перечислены в порядке возрастания.
• Три и более последовательных VLAN перечисляются с дефисом.
• Первая строка списка может быть длиной first_line_len символов.
• Последующие строки списка могут иметь длину other_line_len символов.

Чтобы отсортировать список VLAN:

{{ [3003, 3004, 3005, 100, 1688, 3002, 3999] | ansible.netcommon.vlan_parser }}

Этот пример отображает следующий отсортированный список:

['100,1688,3002-3005,3999']

Ещё один пример шаблона Jinja:

{% set parsed_vlans = vlans | ansible.netcommon.vlan_parser %}
switchport trunk allowed vlan {{ parsed_vlans[0] }}
{% for i in range (1, parsed_vlans | count) %}
switchport trunk allowed vlan add {{ parsed_vlans[i] }}
{% endfor %}

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

Добавление комментариев к файлам

Фильтр ansible.builtin.comment позволяет создавать комментарии в файле из текста в шаблоне с различными стилями комментариев. По умолчанию Ansible использует # для начала строки комментария и добавляет пустую строку комментария сверху и снизу текста комментария. Например:

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

производит этот вывод:

#
# Plain style (default)
#

Ansible предлагает стили комментариев для C (//...), блоков C (/*...*/), Erlang (%...) и XML (<!--...-->):

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

Вы можете определить пользовательский символ комментария. Этот фильтр:

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

производит:

!
! My Special Case
!

Вы можете полностью настроить стиль комментария:

{{ "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

Фильтр urlencode кодирует данные для использования в пути URL или запросе с использованием UTF-8:

{{ 'Trollhättan' | urlencode }}
# => 'Trollh%C3%A4ttan'

Разделение URL

Фильтр ansible.builtin.urlsplit извлекает фрагмент, имя хоста, netloc, пароль, путь, порт, запрос, схему и имя пользователя из 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"
#   }

Поиск в строках с использованием регулярных выражений

Для поиска в строке или извлечения частей строки с помощью регулярного выражения используйте фильтр ansible.builtin.regex_search:

# Extracts the database name from a string
{{ 'server1/database42' | regex_search('database[0-9]+') }}
# => 'database42'

# Example for a case insensitive search in multiline mode
{{ 'foo\nBAR' | regex_search('^bar', multiline=True, ignorecase=True) }}
# => 'BAR'

# Example for a case insensitive search in multiline mode using inline regex flags
{{ 'foo\nBAR' | regex_search('(?im)^bar') }}
# => 'BAR'

# Extracts server and database id from a string
{{ 'server1/database42' | regex_search('server([0-9]+)/database([0-9]+)', '\\1', '\\2') }}
# => ['1', '42']

# Extracts dividend and divisor from a division
{{ '21/42' | regex_search('(?P<dividend>[0-9]+)/(?P<divisor>[0-9]+)', '\\g<dividend>', '\\g<divisor>') }}
# => ['21', '42']

Фильтр ansible.builtin.regex_search возвращает пустую строку, если не найдено совпадение:

{{ 'ansible' | regex_search('foobar') }}
# => ''

{{ 'ansible' | regex_search('foobar') == '' }}
# => False
{{ 'ansible' | regex_search('foobar') is none }}
# => True

Для извлечения всех совпадений регулярных выражений в строке используйте фильтр ansible.builtin.regex_findall:

# Returns 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') }}
# => ['8.8.8.8', '8.8.4.4']

# Returns all lines that end with "ar"
{{ 'CAR\ntar\nfoo\nbar\n' | regex_findall('^.ar$', multiline=True, ignorecase=True) }}
# => ['CAR', 'tar', 'bar']

# Returns all lines that end with "ar" using inline regex flags for multiline and ignorecase
{{ 'CAR\ntar\nfoo\nbar\n' | regex_findall('(?im)^.ar$') }}
# => ['CAR', 'tar', 'bar']

Для замены текста в строке с помощью регулярного выражения используйте фильтр ansible.builtin.regex_replace:

# Convert "ansible" to "able"
{{ 'ansible' | regex_replace('^a.*i(.*)$', 'a\\1') }}
# => 'able'

# Convert "foobar" to "bar"
{{ 'foobar' | regex_replace('^f.*o(.*)$', '\\1') }}
# => 'bar'

# Convert "localhost:80" to "localhost, 80" using named groups
{{ 'localhost:80' | regex_replace('^(?P<host>.+):(?P<port>\\d+)$', '\\g<host>, \\g<port>') }}
# => 'localhost, 80'

# Convert "localhost:80" to "localhost"
{{ 'localhost:80' | regex_replace(':80') }}
# => 'localhost'

# Comment all lines that end with "ar"
{{ 'CAR\ntar\nfoo\nbar\n' | regex_replace('^(.ar)$', '#\\1', multiline=True, ignorecase=True) }}
# => '#CAR\n#tar\nfoo\n#bar\n'

# Comment all lines that end with "ar" using inline regex flags for multiline and ignorecase
{{ 'CAR\ntar\nfoo\nbar\n' | regex_replace('(?im)^(.ar)$', '#\\1') }}
# => '#CAR\n#tar\nfoo\n#bar\n'

# add "https://" prefix to each item in a list
GOOD:
{{ hosts | map('regex_replace', '^(.*)$', 'https://\\1') | list }}
{{ hosts | map('regex_replace', '(.+)', 'https://\\1') | list }}
{{ hosts | map('regex_replace', '^', 'https://') | list }}

BAD:
{{ hosts | map('regex_replace', '(.*)', 'https://\\1') | list }}

# append ':80' to each item in a list
GOOD:
{{ hosts | map('regex_replace', '^(.*)$', '\\1:80') | list }}
{{ hosts | map('regex_replace', '(.+)', '\\1:80') | list }}
{{ hosts | map('regex_replace', '$', ':80') | list }}

BAD:
{{ hosts | map('regex_replace', '(.*)', '\\1:80') | list }}

Для экранирования специальных символов в стандартном регулярном выражении Python используйте фильтр ansible.builtin.regex_escape (используя необязательный параметр re_type='python'):

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

Для экранирования специальных символов в регулярном выражении POSIX basic используйте фильтр ansible.builtin.regex_escape с опцией re_type='posix_basic':

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

Управление именами файлов и именами путей

Для получения последнего имени файла пути, например, ‘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 }}

Для расширения пути, содержащего переменные окружения:

{{ path | expandvars }}

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

{{ path | realpath }}

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

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

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

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

Фильтр ansible.builtin.splitext всегда возвращает пару строк. Отдельные компоненты можно получить с помощью фильтров first и last:

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

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

Для объединения одного или нескольких компонентов пути:

{{ ('/etc', path, 'subdir', file) | path_join }}