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

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

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

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

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

• Версия Python

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

  • Относительные переменные group_vars и host_vars начального playbook'а

• Устаревшие возможности

  • Указание источников инвентаризации
  • Использование нескольких тегов
  • Другие моменты

• Модули

  • Удаленные модули
  • Уведомления об устаревании
  • Заметные изменения в модулях

• Плагины

  • Изменения в плагинах vars
  • Плагины инвентаризации
  • Плагины обратных вызовов
  • Плагин поиска шаблонов: Экранирование строк

• Тесты

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

• Сеть

  • Постоянное соединение
• Настройка

Версия Python

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

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

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

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

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

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

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

Относительные переменные group_vars и host_vars начального playbook'а

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

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