Поиск

Расширения поиска (lookup plugins) дополняют язык шаблонов Jinja2 в Ansible. Они позволяют получать данные из внешних источников (файлов, API, хранилищ типа ключ-значение, баз данных и так далее) во время выполнения сценария. Все операции с расширениями поиска выполняются на управляющем узле.

Все расширения поиска, доступные в Ansible Core, подключаются автоматически. Список доступных расширений и их подробное описание см. в справочнике.

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

Вы можете использовать поиск в различных шаблонах кода Ansible:

• в сценарии;

• в файле определения переменных;

• в шаблоне Jinja2, например, для модуля template.

В Ansible Core доступны две функции для вызова расширений поиска:

• lookup – возвращает строку или список, в зависимости от параметра wantlist. По умолчанию lookup возвращает строку со значениями, разделенными запятыми. Чтобы функция lookup возвращала список, установите параметр wantlist в значение true:

  lookup('ansible.builtin.dict', dict_variable, wantlist=true)
  

• query – всегда возвращает список:

  query('ansible.builtin.dictdict', dict_variable)
  

  Также доступна краткая форма запроса с использованием q вместо query:

  q('ansible.builtin.dictdict', dict_variable)
  

Пример использования расширения ansible.builtin.file для динамического получения содержимого файла и записи его в переменную:

vars:
  file_contents: "{{ lookup('ansible.builtin.file', 'path/to/file.txt') }}"

Расширения поиска являются неотъемлемой частью циклов в Ansible. Директива loop принимает список, который можно задать напрямую или получить через расширение поиска.

Пример использования расширения ansible.builtin.items:

---
# ...
  tasks:
    - name: Using ansible.builtin.items lookup
      ansible.builtin.debug:
        msg: "{{ item }}"
      loop: "{{ lookup('ansible.builtin.items', ['a', 'b', 'c'], wantlist=true) }}"

Вы можете комбинировать поиск с фильтрами, тестами и даже сам с собой для создания сложных данных, например:

---
# ...
  tasks:
    - name: Using lookup with filters together
      ansible.builtin.debug:
        msg: "find the answer here: {{ lookup('ansible.builtin.url', 'https://google.com/search/?q=' + item | urlencode) }}"
      loop: "{{ lookup('ansible.builtin.sequence', start=1, end=3) | list }}"

Безопасность

По умолчанию возвращаемые значения поиска помечаются как небезопасные (unsafe). Если внешний источник надежен, можно передать параметр allow_unsafe=true, чтобы разрешить Jinja2 обрабатывать полученное значение.

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

Некоторые поисковые запросы передают аргументы в оболочку. При использовании переменных из внешнего или ненадежного источника используйте фильтр ansible.builtin.quote для обеспечения безопасного использования.

Управление обработкой ошибок

Чтобы управлять поведением задачи при ошибках поиска, используйте параметр errors.

Возможные значения:

• ignore – игнорировать ошибку:

  ---
  # ...
    tasks:
      - name: Ignore the error and continue playbook execution
        ansible.builtin.debug:
          msg: "File contents: {{ lookup('ansible.builtin.file', '/no/such/file.txt', errors='ignore') | default('<empty>') }}"
  

  Пример вывода:

  TASK [Ignore the error and continue playbook execution]
  
  ok: [localhost] => {
      "msg": "File contents: None"
  }
  

• warn – вывести предупреждение:

  ---
  # ...
    tasks:
      - name: Warn when file is missing
        ansible.builtin.debug:
          msg: "File contents: {{ lookup('ansible.builtin.file', '/no/such/file.txt', errors='warn') | default('<empty>') }}"
  

  Пример вывода:

  TASK [Warn when file is missing]
  
  [WARNING]: Lookup failed but the error is being ignored: The 'file' lookup had an issue accessing the file '/no/such/file.txt'. file not found, use -vvvvv to see paths searched
  
  ok: [localhost] => {
      "msg": "File contents: None"
  }
  

• strict – завершить выполнение задачи с ошибкой:

  ---
  # ...
    tasks:
      - name: Fail strictly if file is missing
        ansible.builtin.debug:
          msg: "File contents: {{ lookup('ansible.builtin.file', '/no/such/file.txt', errors='strict') | default('<empty>') }}"
  

  Пример вывода:

  TASK [Fail strictly if file is missing]
  
  fatal: [localhost]: FAILED! => {"msg": "The 'file' lookup had an issue accessing the file '/no/such/file.txt'. file not found, use -vvvvv to see paths searched"}
  

Значение по умолчанию: strict.