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

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

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

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

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

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

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