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

Включение плагинов поиска
Использование плагинов поиска
Вызов плагинов поиска с query
Список плагинов

Плагины поиска позволяют Ansible получать данные из внешних источников. Это может включать чтение файловой системы помимо подключения к внешним хранилищам данных и службам. Как и все шаблоны, эти плагины обрабатываются на управляющей машине Ansible, а не на целевом/удалённом узле.

Возвращаемые плагином поиска данные доступны через стандартную систему шаблонов Ansible и обычно используются для загрузки переменных или шаблонов с информацией из этих систем.

Поиск — это специфичное для Ansible расширение языка шаблонов Jinja2.

Примечание

Поиск выполняется с рабочей директорией, относительной к роли или заданию, в отличие от локальных задач, которые выполняются относительно исполняемого скрипта.
С версии Ansible 1.9 вы можете передавать wantlist=True в поиски, чтобы использовать их в циклах Jinja2.
Плагины поиска — это расширенная функция; для их эффективного использования необходимо хорошо разбираться в работе с заданиями Ansible.

Предупреждение

Некоторые поиски передают аргументы в оболочку. При использовании переменных из удалённого/ненадёжного источника используйте фильтр |quote, чтобы обеспечить безопасное использование.

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

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

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

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

Добавлена в версии 2.6.

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

Для игнорирования ошибок:

- name: file doesnt exist, but i dont care .. file plugin itself warns anyways ...
  debug: msg="{{ lookup('file', '/idontexist', errors='ignore') }}"

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

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

Для получения предупреждения вместо ошибки:

- name: file doesnt exist, let me know, but continue
  debug: msg="{{ lookup('file', '/idontexist', errors='warn') }}"

[WARNING]: Unable to find '/idontexist' 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: /idontexist

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

Критическая ошибка (значение по умолчанию):

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

[WARNING]: Unable to find '/idontexist' 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: /idontexist"}

Вызов плагинов поиска с `query`

Добавлена в версии 2.5.

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

См. также

О плейбуках: Введение в плейбуки
Плагины инвентаризации: Плагины инвентаризации Ansible
Плагины обратного вызова: Плагины обратного вызова Ansible
Фильтры: Плагины фильтра Jinja2
Тесты: Плагины тестирования Jinja2
Поиск: Плагины поиска Jinja2
Список рассылки пользователей: Есть вопрос? Загляните в группу Google!
irc.freenode.net: Канал IRC-чата #ansible

© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.9/plugins/lookup.html