Руководство по переносу 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, который был выполнен. Это позволяло последовательно включенным playbook из других директорий наследовать 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. Пожалуйста, обновите свои playbook соответственно.

• azure, используйте azure_rm_virtualmachine, который использует новый SDK Resource Manager.
• 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) были сохранены для обратной совместимости, но будут предупреждать пользователей о том, что функция устарела.

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