Руководство по переносу Ansible 2.4

В этом разделе рассматриваются изменения в поведении между Ansible 2.3 и Ansible 2.4.

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

Мы рекомендуем вам прочитать эту страницу вместе с Журналом изменений Ansible 2.4, чтобы понять, какие обновления вам могут потребоваться.

Этот документ является частью коллекции по переносу. Полный список руководств по переносу можно найти по адресу руководствам по переносу.

• Версия Python
• Инвентаризация
  • Исходные playbook относительные group_vars и host_vars
• Устаревшие
  • Указание источников инвентаризации
  • Использование нескольких тегов
  • Другие замечания
• Модули
  • Удаленные модули
  • Уведомления об устаревании
  • Заметные изменения модулей
• Плагины
  • Изменения плагина vars
  • Плагины инвентаризации
  • Плагины обратных вызовов
  • Плагин поиска шаблонов: Экранирование строк
• Тесты
  • Тесты выполнены/не выполнены
• Сети
  • Постоянное соединение
• Настройка

Версия Python

Ansible больше не будет поддерживать Python 2.4 или 2.5 на целевых хостах. В дальнейшем потребуется Python 2.6+ на целевых машинах, как это уже есть на контроллере.

Инвентаризация

Инвентаризация была переработана для реализации через плагины и теперь позволяет использовать несколько источников. Это изменение в основном прозрачно для пользователей.

Исключение составляет inventory_dir, который теперь является переменной хоста; ранее он мог иметь только одно значение, поэтому он устанавливался глобально. Это означает, что вы больше не можете использовать его на ранних этапах выполнения, чтобы определить hosts: или аналогичные ключевые слова. Это также меняет поведение add_hosts и неявного localhost; поскольку они больше не автоматически наследуют глобальное значение, они по умолчанию устанавливаются в None. Дополнительную информацию см. в документации модуля.

inventory_file остается в основном без изменений, так как он всегда был специфичен для хоста.

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

Была исправлена ошибка с путем/каталогом инвентаризации, который по умолчанию устанавливался в текущий рабочий каталог. Это привело к тому, что group_vars и host_vars были взяты из текущего рабочего каталога вместо расположения рядом с playbook или каталогом инвентаризации, когда список хостов (разделенных запятыми имена хостов) предоставлялся в качестве инвентаризации.

Исходные playbook относительные group_vars и host_vars

В версиях Ansible до 2.4 система инвентаризации сохраняла контекст исходного playbook, который был выполнен. Это позволяло последовательно включенным playbooks из других каталогов наследовать group_vars и host_vars, размещенные относительно файла playbook верхнего уровня.

Из-за некоторых несоответствий в поведении эта функция не будет включена в новую систему инвентаризации, начиная с Ansible версии 2.4.

Аналогичный функционал все еще можно достичь, используя vars_files, include_vars, или group_vars и host_vars, размещенные относительно файла инвентаризации.

Устаревшие

Указание источников инвентаризации

Использование --inventory-file в командной строке теперь устарело. Используйте --inventory или -i. Соответствующий ключ конфигурации ini, hostfile, и переменная среды ANSIBLE_HOSTS, также устарели. Замените их ключом конфигурации inventory и переменной среды ANSIBLE_INVENTORY.

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

Указание --tags (или --skip-tags) несколько раз в командной строке в настоящее время приводит к тому, что последнее переопределяет все предыдущие. Это поведение устарело. В будущем, если вы укажете –tags несколько раз, теги будут объединены. С этого момента использование --tags несколько раз в одной командной строке будет выводить предупреждение об устаревании. Установка параметра merge_multiple_cli_tags в значение True в файле ansible.cfg включит новое поведение.

В версии 2.4 по умолчанию изменилось на объединение тегов. Вы можете включить старое поведение переопределения с помощью параметра конфигурации.

В версии 2.5 несколько --tags опций будут объединены без возможности вернуться к старому поведению.

Другие замечания

В этой версии нет существенных изменений.

Модули

Основные изменения в популярных модулях подробно описаны здесь

• Модули win_shell и win_command теперь правильно сохраняют цитируемые аргументы в командной строке. Задачи, которые пытались обойти проблему путем добавления дополнительных кавычек/экранирования, могут потребовать переработки для удаления избыточного экранирования. Дополнительные сведения см. в проблеме 23019.

Удаленные модули

Следующие модули больше не существуют:

• Нет

Уведомления об устаревании

Следующие модули будут удалены в Ansible 2.8. Пожалуйста, обновите свои playbooks соответственно.

• azure, используйте azure_rm_virtualmachine, который использует новый SDK для управления ресурсами.
• win_msi, используйте win_package вместо него

Заметные изменения модулей

• В модуле win_get_url словарь win_get_url в результатах устарел, его содержимое теперь также доступно непосредственно в выходном результатах, как и в других модулях. Этот словарь будет удален в Ansible 2.8.
• Модуль win_unzip больше не включает словарь win_unzip в своих результатах; содержимое теперь включено непосредственно в выходной результат, как и в других модулях.
• Значения возврата модуля win_package exit_code и restart_required устарели в пользу rc и reboot_required соответственно. Устаревшие значения возврата будут удалены в Ansible 2.6.

Плагины

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

Изменения плагина vars

Было много изменений в реализации плагинов vars, но пользователям и разработчикам не нужно ничего менять, чтобы сохранить работоспособность текущих установок. Разработчики должны рассмотреть возможность изменения своих плагинов для использования новых возможностей.

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

Плагины инвентаризации

Разработчики должны начать переход от жестко закодированной инвентаризации с динамическими скриптами инвентаризации к новым плагинам инвентаризации. Скрипты все еще будут работать через плагин инвентаризации script, но усилия по разработке Ansible теперь будут сосредоточены на написании плагинов, а не на улучшении существующих скриптов.

Как пользователи, так и разработчики должны изучить новые плагины, поскольку они призваны устранить необходимость во многих хаках и обходных путях, встречающихся в динамических скриптах инвентаризации.

Плагины обратных вызовов

Пользователи:

• Плагины обратных вызовов теперь используют новую систему конфигурации. Пользователям не нужно ничего менять, так как старая система по-прежнему работает, но вы можете увидеть предупреждение об устаревании, если используемые плагины обратных вызовов не наследуют от встроенных классов. Разработчики должны обновить их, как указано ниже.

Разработчики:

• Если ваш обратный вызов не наследуется от CallbackBase (прямо или косвенно через другой обратный вызов), он всё равно будет работать, но выведет сообщение о устаревании. Чтобы избежать этого и гарантировать работоспособность в будущем, измените его так, чтобы он наследовался от CallbackBase, чтобы он имел новые методы и свойства обработки параметров. Вы также можете реализовать новые методы и свойства обработки параметров, но это не гарантирует автоматического наследования изменений, добавленных в будущем. Вы можете посмотреть подробности в CallbackBase и/или AnsiblePlugin.
• Любые обратные вызовы, наследующиеся от других обратных вызовов, могут потребовать обновления, чтобы содержать те же документированные параметры, что и родительский вызов, иначе параметры не будут доступны. Это отмечено в руководстве разработчика.

Плагин поиска шаблонов: Экранирование строк

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

Если у вас есть поиск шаблонов такого вида:

- debug:
    msg: '{{ lookup("template", "template.j2") }}'

СТАРЫЙ В Ansible 2.3 (и ранее) template.j2 выглядел так:

{{ "name surname" | regex_replace("^[^\s]+\s+(.*)", "\1") }}

НОВЫЙ В Ansible 2.4 его следует изменить на:

{{ "name surname" | regex_replace("^[^\\s]+\\s+(.*)", "\\1") }}

Тесты

Успешные/неуспешные тесты

До версии Ansible 2.4 код возврата задачи rc переопределял код возврата failed. В версии 2.4 как rc, так и failed используются для расчета состояния задачи. Из-за этого плагины тестов succeeded/failed` также были изменены. Это означает, что переопределение неудачи задачи с помощью failed_when: no приведет к тому, что succeeded/failed вернут True/False. Например:

- command: /bin/false
  register: result
  failed_when: no

- debug:
    msg: 'This is printed on 2.3'
  when: result|failed

- debug:
    msg: 'This is printed on 2.4'
  when: result|succeeded

- debug:
    msg: 'This is always printed'
  when: result.rc != 0

Как видно из примера выше, в Ansible 2.3 succeeded/failed проверяли только значение rc.

Сеть

Было внесено множество изменений в работу модулей сети.

Плейбуки по-прежнему должны использовать connection: local.

Персистентное соединение

Переменные конфигурации connection_retries и connect_interval, добавленные в Ansible 2.3, теперь устарели. Для Ansible 2.4 и более поздних версий используйте connection_retry_timeout.

Для управления таймаутами используйте command_timeout, а не предыдущую переменную верхнего уровня timeout в [default]

Для получения дополнительной информации см. Руководство по отладке сети Ansible.

Конфигурация

Система конфигурации претерпела существенные изменения. Пользователи, как правило, не должны столкнуться с проблемами, кроме следующих:

• Все относительные пути определяются относительно самого файла ansible.cfg. Ранее они различались в зависимости от настроек. Новое поведение должно быть более предсказуемым.
• Доступен новый макрос {{CWD}} для путей, который сделает пути относительными к текущей рабочей директории. Это небезопасно, но некоторые пользователи действительно хотят полагаться на это поведение.

Разработчики, работающие напрямую с предыдущим API, должны пересмотреть своё использование, так как некоторые методы (например, get_config) были сохранены для обратной совместимости, но будут предупреждать пользователей о том, что функция устарела.

Новая конфигурация разработана с целью минимизации необходимости внесения изменений в ядро для новых плагинов. Плагинам просто нужно задокументировать свои настройки, и система конфигурации будет использовать документацию для получения необходимых данных. Это всё ещё в стадии разработки; в настоящее время эту поддержку имеют только плагины «обратного вызова» и «соединения». Более подробные сведения будут добавлены в конкретные руководства разработчиков плагинов.