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

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

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

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

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

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

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

q('dict', dict_variable)

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

Чтобы просмотреть список доступных плагинов, используйте ansible-doc -t lookup -l. Для просмотра документации и примеров, относящихся к конкретному плагину, используйте ansible-doc -t lookup <plugin name>.