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

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

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

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

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

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

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

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> для просмотра конкретных документов и примеров.