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

Задание значений по умолчанию

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

{{ some_variable | default(5) }}

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

Начиная с версии 2.8, попытка получить атрибут значения Undefined в Jinja возвращает другое значение Undefined, а не сразу вызывает ошибку. Это означает, что теперь можно просто использовать значение по умолчанию во вложенной структуре данных (другими словами, {{ 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 определяется маской создания файлов системы (umask). Ansible не передаёт значение для mode. Параметр mode=0444 получает только третий файл, /tmp/baz.

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

Если вы настроили 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 создает произведение объекта и значений его вложенных элементов, подобно lookup-плагину 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', поведение аналогично append_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 }}"
# => [(1, 2, 3, 4, 5), (1, 2, 3, 5, 4), (1, 2, 4, 3, 5), (1, 2, 4, 5, 3), (1, 2, 5, 3, 4), (1, 2, 5, 4, 3), (1, 3, 2, 4, 5), (1, 3, 2, 5, 4), (1, 3, 4, 2, 5), (1, 3, 4, 5, 2), (1, 3, 5, 2, 4), (1, 3, 5, 4, 2), (1, 4, 2, 3, 5), (1, 4, 2, 5, 3), (1, 4, 3, 2, 5), (1, 4, 3, 5, 2), (1, 4, 5, 2, 3), (1, 4, 5, 3, 2), (1, 5, 2, 3, 4), (1, 5, 2, 4, 3), (1, 5, 3, 2, 4), (1, 5, 3, 4, 2), (1, 5, 4, 2, 3), (1, 5, 4, 3, 2), (2, 1, 3, 4, 5), (2, 1, 3, 5, 4), (2, 1, 4, 3, 5), (2, 1, 4, 5, 3), (2, 1, 5, 3, 4), (2, 1, 5, 4, 3), (2, 3, 1, 4, 5), (2, 3, 1, 5, 4), (2, 3, 4, 1, 5), (2, 3, 4, 5, 1), (2, 3, 5, 1, 4), (2, 3, 5, 4, 1), (2, 4, 1, 3, 5), (2, 4, 1, 5, 3), (2, 4, 3, 1, 5), (2, 4, 3, 5, 1), (2, 4, 5, 1, 3), (2, 4, 5, 3, 1), (2, 5, 1, 3, 4), (2, 5, 1, 4, 3), (2, 5, 3, 1, 4), (2, 5, 3, 4, 1), (2, 5, 4, 1, 3), (2, 5, 4, 3, 1), (3, 1, 2, 4, 5), (3, 1, 2, 5, 4), (3, 1, 4, 2, 5), (3, 1, 4, 5, 2), (3, 1, 5, 2, 4), (3, 1, 5, 4, 2), (3, 2, 1, 4, 5), (3, 2, 1, 5, 4), (3, 2, 4, 1, 5), (3, 2, 4, 5, 1), (3, 2, 5, 1, 4), (3, 2, 5, 4, 1), (3, 4, 1, 2, 5), (3, 4, 1, 5, 2), (3, 4, 2, 1, 5), (3, 4, 2, 5, 1), (3, 4, 5, 1, 2), (3, 4, 5, 2, 1), (3, 5, 1, 2, 4), (3, 5, 1, 4, 2), (3, 5, 2, 1, 4), (3, 5, 2, 4, 1), (3, 5, 4, 1, 2), (3, 5, 4, 2, 1), (4, 1, 2, 3, 5), (4, 1, 2, 5, 3), (4, 1, 3, 2, 5), (4, 1, 3, 5, 2), (4, 1, 5, 2, 3), (4, 1, 5, 3, 2), (4, 2, 1, 3, 5), (4, 2, 1, 5, 3), (4, 2, 3, 1, 5), (4, 2, 3, 5, 1), (4, 2, 5, 1, 3), (4, 2, 5, 3, 1), (4, 3, 1, 2, 5), (4, 3, 1, 5, 2), (4, 3, 2, 1, 5), (4, 3, 2, 5, 1), (4, 3, 5, 1, 2), (4, 3, 5, 2, 1), (4, 5, 1, 2, 3), (4, 5, 1, 3, 2), (4, 5, 2, 1, 3), (4, 5, 2, 3, 1), (4, 5, 3, 1, 2), (4, 5, 3, 2, 1), (5, 1, 2, 3, 4), (5, 1, 2, 4, 3), (5, 1, 3, 2, 4), (5, 1, 3, 4, 2), (5, 1, 4, 2, 3), (5, 1, 4, 3, 2), (5, 2, 1, 3, 4), (5, 2, 1, 4, 3), (5, 2, 3, 1, 4), (5, 2, 3, 4, 1), (5, 2, 4, 1, 3), (5, 2, 4, 3, 1), (5, 3, 1, 2, 4), (5, 3, 1, 4, 2), (5, 3, 2, 1, 4), (5, 3, 2, 4, 1), (5, 3, 4, 1, 2), (5, 3, 4, 2, 1), (5, 4, 1, 2, 3), (5, 4, 1, 3, 2), (5, 4, 2, 1, 3), (5, 4, 2, 3, 1), (5, 4, 3, 1, 2), (5, 4, 3, 2, 1)]

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

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

{{ ['foo', 'bar'] | product(['com']) }}
# => [('foo', 'com'), ('bar', 'com')]

{{ ['foo', 'bar'] | product(['com']) | map('join', '.') }}
# => ['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 расширяет стандартный фильтр random в Jinja2. Его можно использовать для выбора случайного элемента из последовательности или для генерации случайного числа в заданном диапазоне.

Чтобы получить случайный элемент из списка:

"{{ ['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.

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

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

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

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

Файл спецификации должен быть корректно отформатированным документом YAML. В нем задается, как разбирать вывод CLI и возвращать данные 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. Чтобы разобрать вывод CLI с помощью 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. Этот список обладает следующими свойствами:

• VLAN перечислены в порядке возрастания.
• Три и более последовательных 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
#
#######
   ###
    #

URL-кодирование переменных

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

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

Разделение URL-адресов

Фильтр ansible.builtin.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"
#   }

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

Чтобы выполнить поиск в строке или извлечь из неё части с помощью регулярного выражения, используйте фильтр 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_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, используйте фильтр 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 }}