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

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

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

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

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

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

Вы можете активировать пользовательский поиск, поместив его в директорию 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']

Теперь вы можете управлять поведением ошибок во всех плагинах поиска, установив 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

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

• aws_account_attribute – Вывод атрибутов учетной записи AWS
• aws_secret – Вывод секретов, хранящихся в AWS Secrets Manager
• aws_service_ip_ranges – Вывод диапазонов IP-адресов для сервисов AWS, таких как EC2 и S3
• aws_ssm – Получение значения параметра SSM или всех параметров в заданном пути
• cartesian – Возвращает декартово произведение списков
• chef_databag – Получение данных из Chef Databag
• config – Вывод текущих значений конфигурации Ansible
• conjur_variable – Получение учетных данных из CyberArk Conjur
• consul_kv – Получение метаданных из хранилища Consul key-value
• cpm_metering – Получение данных мощности и тока от устройств WTI OOB/Combo и PDU
• cpm_status – Получение статуса и параметров устройств WTI OOB и PDU
• credstash – Получение секретов из Credstash на AWS
• csvfile – чтение данных из файла TSV или CSV
• cyberarkpassword – получение секретов из CyberArk AIM
• dict – возвращает пары ключ/значение из словарей
• dig – запрос DNS с использованием библиотеки dnspython
• dnstxt – запрос DNS-текстовых полей домена(ов)
• env – чтение значения переменных среды
• etcd – получение информации с сервера etcd
• file – чтение содержимого файла
• fileglob – список файлов, соответствующих шаблону
• filetree – рекурсивный поиск всех файлов в древовидной структуре каталогов
• first_found – возвращает первый найденный файл из списка
• flattened – возвращает полностью уплощенный единый список
• grafana_dashboard – вывод или поиск панелей управления Grafana
• hashi_vault – извлечение секретов из хранилища HashiCorp’s vault
• hiera – получение информации из данных hiera
• indexed_items – переписывает списки для возврата «индексированных элементов»
• ini – чтение данных из файла ini
• inventory_hostnames – список хостов инвентаризации, соответствующих шаблону хоста
• items – список элементов
• k8s – Запрос к API K8s
• keyring – извлечение секретов из системного хранилища ключей
• laps_password – Извлечение пароля LAPS для сервера
• lastpass – извлечение данных из lastpass
• lines – чтение строк из команды
• list – просто возвращает полученное значение
• manifold – получение учетных данных от Manifold.co
• mongodb – вывод информации из MongoDB
• nested – формирует список со вложенными элементами из других списков
• nios – Запрос к объектам Infoblox NIOS
• nios_next_ip – Возвращает следующий доступный IP-адрес для сети
• nios_next_network – Возвращает следующий доступный диапазон сети для сетевого контейнера
• onepassword – извлечение значений полей из 1Password
• onepassword_raw – извлечение всего элемента из 1Password
• openshift – Запрос к API K8s
• password – извлечение или генерация случайного пароля, хранящегося в файле
• passwordstore – управление паролями с помощью утилиты pass passwordstore.org
• pipe – чтение вывода из команды
• rabbitmq – Извлечение сообщений из очереди RabbitMQ AMQP/AMQPS
• random_choice – возвращает случайный элемент из списка
• redis – извлечение данных из Redis
• redis_kv – извлечение данных из Redis
• sequence – генерация списка на основе числовой последовательности
• shelvefile – чтение ключей из файла Python shelve
• skydive – Запрос к объектам Skydive
• subelements – обход вложенных ключей из списка словарей
• template – извлечение содержимого файла после применения шаблонизации с Jinja2
• together – объединяет списки в синхронизированный список
• url – возврат содержимого из URL
• varnames – Поиск соответствующих имен переменных
• vars – Поиск шаблонизированного значения переменных