Плагины поиска

• Включение плагинов поиска
• Использование плагинов поиска
• Принудительное возвращение результатов поиска в виде списков: query и wantlist=True
• Список плагинов

Плагины поиска — это специфичные для Ansible расширения языка шаблонизации Jinja2. Вы можете использовать плагины поиска для доступа к данным из внешних источников (файлов, баз данных, хранилищ ключей/значений, API и других сервисов) в ваших playbook-файлах. Как и все шаблоны, запросы выполняются и оцениваются на контрольном компьютере Ansible. Ansible предоставляет данные, возвращаемые плагином поиска, с использованием стандартной системы шаблонизации. Вы можете использовать плагины поиска для загрузки переменных или шаблонов с информацией из внешних источников.

Включение плагинов поиска

Ansible включает все найденные плагины поиска. Вы можете активировать пользовательский плагин, поместив его в каталог lookup_plugins рядом с вашей задачей, в каталог plugins/lookup/ коллекции, которую вы установили, в автономной роли или в одном из каталогов источников поиска, настроенных в ansible.cfg.

Использование плагинов поиска

Вы можете использовать плагины поиска там, где вы можете использовать шаблоны в Ansible: в play-файле, в файле переменных или в шаблоне Jinja2 для модуля шаблон.

vars:
  file_contents: "{{ lookup('file', 'path/to/file.txt') }}"

Поисковые запросы являются неотъемлемой частью циклов. Всюду, где вы видите with_, часть после нижнего подчеркивания — это имя поиска. По этой причине большинство поисковых запросов выводят списки и принимают списки в качестве входных данных; например, with_items использует поиск items:

tasks:
  - name: count to 3
    debug: msg={{ item }}
    with_items: [1, 2, 3]

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

tasks:
  - name: valid but useless and over complicated chained lookups and filters
    debug: msg="find the answer here:\n{{ lookup('url', 'https://google.com/search/?q=' + item|urlencode)|join(' ') }}"
    with_nested:
      - "{{ lookup('consul_kv', 'bcs/' + lookup('file', '/the/question') + ', host=localhost, port=2000')|shuffle }}"
      - "{{ lookup('sequence', 'end=42 start=2 step=2')|map('log', 4)|list) }}"
      - ['a', 'c', 'd', 'c']

Вы можете управлять поведением ошибок во всех плагинах поиска, установив errors на ignore, warn или strict. Значение по умолчанию — strict, что приводит к завершению задачи с ошибкой, если поиск возвращает ошибку. Например:

Чтобы проигнорировать ошибки поиска:

- name: if this file does not exist, I do not care .. file plugin itself warns anyway ...
  debug: msg="{{ lookup('file', '/nosuchfile', errors='ignore') }}"

[WARNING]: Unable to find '/nosuchfile' in expected paths (use -vvvvv to see paths)

ok: [localhost] => {
    "msg": ""
}

Чтобы получить предупреждение вместо ошибки:

- name: if this file does not exist, let me know, but continue
  debug: msg="{{ lookup('file', '/nosuchfile', errors='warn') }}"

[WARNING]: Unable to find '/nosuchfile' in expected paths (use -vvvvv to see paths)

[WARNING]: An unhandled exception occurred while running the lookup plugin 'file'. Error was a <class 'ansible.errors.AnsibleError'>, original message: could not locate file in lookup: /nosuchfile

ok: [localhost] => {
    "msg": ""
}

Чтобы получить ошибку (по умолчанию):

- name: if this file does not exist, FAIL (this is the default)
  debug: msg="{{ lookup('file', '/nosuchfile', errors='strict') }}"

[WARNING]: Unable to find '/nosuchfile' in expected paths (use -vvvvv to see paths)

fatal: [localhost]: FAILED! => {"msg": "An unhandled exception occurred while running the lookup plugin 'file'. Error was a <class 'ansible.errors.AnsibleError'>, original message: could not locate file in lookup: /nosuchfile"}

Принудительное возвращение результатов поиска в виде списков: query и wantlist=True

В Ansible 2.5 был добавлен новый Jinja2-функция под названием query для вызова плагинов поиска. Разница между lookup и query в основном в том, что query всегда возвращает список. По умолчанию lookup возвращает строку с значениями, разделёнными запятыми. lookup можно явно настроить на возврат списка, используя wantlist=True.

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

Следующие примеры эквивалентны:

lookup('dict', dict_variable, wantlist=True)

query('dict', dict_variable)

Как показано выше, поведение wantlist=True подразумевается при использовании query.

Кроме того, q был введен как сокращенная форма query:

q('dict', dict_variable)

Список плагинов

Вы можете использовать ansible-doc -t lookup -l для просмотра списка доступных плагинов. Используйте ansible-doc -t lookup <plugin name> для просмотра конкретных документов и примеров.