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

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

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

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

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