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

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

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

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

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

Playbook
- Динамические включения и наследование атрибутов
- Исправленная обработка ключевых слов и встроенных переменных
Устаревшие элементы
- Тесты Jinja, используемые как фильтры
Модули
Плагины
Перенос пользовательских скриптов
Сеть

Playbook

Динамические включения и наследование атрибутов

В версии Ansible 2.4 было введено понятие динамических включений (include_tasks) по сравнению со статическими импортами (import_tasks) для четкого определения различий в том, как include работает в динамических и статических включениях.

Все атрибуты, применённые к динамическому include_*, применялись только к самому включению, в то время как атрибуты, применённые к статическому import_*, наследовались задачами внутри него.

Это разделение было только частично реализовано в Ansible 2.4. Начиная с Ansible 2.5, эта работа завершена, и разделение теперь работает как задумывалось; атрибуты, применённые к задаче include_*, не будут наследоваться внутренними задачами.

Чтобы добиться результата, аналогичного тому, как работал Ansible до версии 2.5, playbook должны использовать явное применение атрибута к необходимым задачам или использовать блоки для применения атрибута к множеству задач. Ещё один вариант — использовать статический import_*, когда это возможно, вместо динамической задачи.

СТАРЫЙ В Ansible 2.4:

- include_tasks: "{{ ansible_distribution }}.yml"
  tags:
    - distro_include

Включаемый файл:

- block:
    - debug:
        msg: "In included file"

    - apt:
        name: nginx
        state: latest

НОВЫЙ В Ansible 2.5:

Включение задачи:

- include_tasks: "{{ ansible_distribution }}.yml"
  tags:
    - distro_include

Включаемый файл:

- block:
    - debug:
        msg: "In included file"

    - apt:
        name: nginx
        state: latest
  tags:
    - distro_include

Соответствующее изменение в этих примерах заключается в том, что в Ansible 2.5 включенный файл определяет тег distro_include снова. Этот тег не наследуется автоматически.

Исправленная обработка ключевых слов и встроенных переменных

Мы внесли несколько исправлений в обработку ключевых слов и «встроенных переменных», чтобы избежать их смешивания. К сожалению, эти изменения означают, что вы должны указать, является ли name ключевым словом или переменной при вызове ролей. Если у вас есть playbook, похожие на этот:

roles:
    - { role: myrole, name: Justin, othervar: othervalue, become: True}

Вы столкнётесь с ошибками, потому что Ansible читает имя в этом контексте как ключевое слово. Начиная с версии 2.5, если вы хотите использовать имя переменной, которое также является ключевым словом, вы должны явно объявить его как переменную для роли:

roles:
    - { role: myrole, vars: {name: Justin, othervar: othervalue}, become: True}

Полный список ключевых слов см. в ::ref::Playbook Keywords.

Устаревшие элементы

Тесты Jinja, используемые как фильтры

Использование предоставляемых Ansible тестов Jinja в качестве фильтров будет удалено в Ansible 2.9.

До Ansible 2.5, тесты Jinja, включенные в Ansible, чаще всего использовались как фильтры. Существенное различие в использовании заключается в том, что фильтры ссылаются как variable | filter_name , а тесты Jinja — как variable is test_name.

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

Начиная с Ansible 2.5, использование предоставленного Ansible теста Jinja с синтаксисом фильтра выведет предупреждение об устаревании.

СТАРЫЙ В Ansible 2.4 (и ранее) использование теста Jinja, включенного в Ansible, могло выглядеть так:

when:
    - result | failed
    - not result | success

НОВЫЙ В Ansible 2.5 он должен быть изменён следующим образом:

when:
    - result is failed
    - results is not successful

Помимо предупреждений об устаревании, было введено множество новых тестов, являющихся алиасами старых тестов. Эти новые тесты грамматически более осмысленны в синтаксисе Jinja-тестов, например, новый тест successful, который является алиасом success.

when: result is successful

См. Тесты для получения дополнительной информации.

Кроме того, был создан скрипт для помощи в преобразовании тестов, использующих синтаксис фильтров, в правильный синтаксис тестов Jinja. Этот скрипт использовался для преобразования всех интеграционных тестов Ansible в правильный формат. Существует несколько ограничений, задокументированных в нём, и все изменения, внесённые этим скриптом, должны быть проверены на корректность перед выполнением изменённых playbook. Скрипт можно найти по адресу https://github.com/ansible/ansible/blob/devel/hacking/fix_test_syntax.py.

Модули

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

github_release

В версиях Ansible 2.4 и ранее, после создания выпуска GitHub с помощью состояния create_release, модуль github_release сообщал состояние как skipped. В Ansible 2.5 и более поздних версиях, после создания выпуска GitHub с помощью состояния create_release, модуль github_release теперь сообщает состояние как changed.

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

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

nxos_mtu используйте опцию nxos_system‘s system_mtu или nxos_interface вместо неё
cl_interface_policy используйте nclu вместо неё
cl_bridge используйте nclu вместо неё
cl_img_install используйте nclu вместо неё
cl_ports используйте nclu вместо неё
cl_license используйте nclu вместо неё
cl_interface используйте nclu вместо неё
cl_bond используйте nclu вместо неё
ec2_vpc используйте ec2_vpc_net вместе с поддерживающими модулями ec2_vpc_igw, ec2_vpc_route_table, ec2_vpc_subnet, ec2_vpc_dhcp_option, ec2_vpc_nat_gateway, ec2_vpc_nacl вместо неё.
ec2_ami_search используйте ec2_ami_facts вместо неё
docker используйте docker_container и docker_image вместо неё

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

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

Модули Apstra’s aos_* устарели, так как они не работают с AOS 2.1 или более поздними версиями. См. новые модули на https://github.com/apstra.
nxos_ip_interface используйте nxos_l3_interface вместо неё.
nxos_portchannel используйте nxos_linkagg вместо неё.
nxos_switchport используйте nxos_l2_interface вместо неё.
panos_security_policy используйте panos_security_rule вместо неё.
panos_nat_policy используйте panos_nat_rule вместо неё.
vsphere_guest используйте vmware_guest вместо неё.

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

Модули stat и win_stat изменили значение по умолчанию опции get_md5 с true на false.

Эта опция будет удалена, начиная с версии Ansible 2.9. Опции get_checksum: True и checksum_algorithm: md5 по-прежнему могут использоваться, если требуется контрольная сумма MD5.

osx_say модуль был переименован в say.
Модуль lineinfile был изменён в 2.5.6, чтобы отображать предупреждение при использовании пустой строки в качестве регулярного выражения. Поскольку пустое регулярное выражение соответствует каждой строке в файле, оно заменит последнюю строку в файле вместо вставки. Если это желаемое поведение, используйте '^', которое будет соответствовать каждой строке и не вызовет предупреждения.
Несколько модулей, которые могли обрабатывать символические ссылки, изменили значение по умолчанию своей опции follow в рамках функции по стандартизации поведения follow:
- Модуль file module изменился с follow=False на follow=True, потому что его цель — изменить атрибуты файла, а большинство систем не позволяют применять атрибуты к символическим ссылкам, только к реальным файлам.
- Параметр follow модуля replace module был удалён, потому что он по своей сути изменяет содержимое существующего файла, поэтому не имеет смысла выполнять операцию над самой ссылкой.
- Параметр follow модуля blockinfile module был удалён, потому что он по своей сути изменяет содержимое существующего файла, поэтому не имеет смысла выполнять операцию над самой ссылкой.
- В Ansible-2.5.3 модуль template module стал более строгим по отношению к файлу src, требуя правильного кодирования utf-8. Раньше, если в файле шаблона модуля src отсутствовало кодирование utf-8, то в выходном файле получались повреждённые данные (символы, не соответствующие utf-8, заменялись символом замены юникода). Теперь в Python2 модуль выдаст ошибку с сообщением «Файлы шаблонов должны быть закодированы в utf-8». В Python3 модуль сначала попытается пройтись по символам не-utf8 в исходном виде и выдать ошибку, если это не сработает.

Плагины

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

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

Плагины инвентаризации были доработаны, и мы начали добавлять некоторые общие функции:

Возможность использования плагина кеширования для избежания дорогостоящих запросов к API/БД отключена по умолчанию. Если вы используете скрипты инвентаризации, некоторые из них могут уже поддерживать кеширование, но это не входит в область знаний и контроля Ansible. Переход к внутреннему кешированию позволит использовать существующие механизмы обновления/очистки кеша Ansible.
Новый плагин «auto», включённый по умолчанию, который может автоматически определить правильный плагин для использования, ЕСЛИ этот плагин использует наш «общий формат конфигурации YAML». Предыдущие плагины host_list, script, yaml и ini по-прежнему работают так же, как и раньше, плагин auto теперь является последним, который мы пытаемся использовать. Если вы настраивали включенные плагины, вам следует пересмотреть настройки, чтобы добавить новый плагин auto.

Командная строка

Плагины командной строки были перенесены в новую систему конфигурации плагинов. Теперь можно настроить больше параметров, и параметры, которые ранее были «глобальными», теперь также могут быть переопределены с помощью переменных хостов.

Например, system_temps — новая настройка, которая позволяет управлять тем, что Ansible будет считать «временной системной директорией». Это используется при повышении привилегий для пользователя, не являющегося администратором. Ранее это было жёстко задано как «/tmp», что некоторые системы не могут использовать для повышения привилегий. Теперь эта настройка по умолчанию установлена в [ '/var/tmp', '/tmp'].

Ещё одна новая настройка — admin_users, которая позволяет указать список пользователей, которые считаются «администраторами». Раньше это было жёстко задано как root. Теперь по умолчанию это [root, toor, admin]. Эта информация используется при выборе между вашей директорией remote_temp и директорией system_temps.

END_OF_DOCUMENT_MARKER

Для полного списка проверьте используемый вами плагин оболочки, по умолчанию используется плагин оболочки sh.

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

Фильтр

API плагина поиска теперь выдает ошибку, если из плагина возвращается неитерируемое значение. Ранее числа или другие неитерируемые типы, возвращаемые плагином, принимались без ошибок или предупреждений. Это изменение было сделано, потому что плагины всегда должны возвращать список. Обратите внимание, что плагины, возвращающие строки и другие несписочные итерируемые значения, не будут вызывать ошибку, но могут привести к непредсказуемому поведению. Если у вас есть пользовательский плагин поиска, который не возвращает список, вы должны изменить его, чтобы обернуть возвращаемые значения в список.

Поиск

Было добавлено новое глобальное свойство для плагинов поиска, называемое error, которое позволяет контролировать обработку ошибок, создаваемых поиском, прежде чем это свойство всегда было фатальным. Допустимые значения для этого свойства — warn, ignore и strict. См. страницу поиска для получения более подробной информации.

Перенос пользовательских скриптов

Нет заметных изменений.

Сеть

Расширение документации

Мы расширяем документацию по сети. Есть новые материалы и новая стартовая страница Ansible Network. Мы продолжим развитие документации по сетям.

Аргументы подключения верхнего уровня будут удалены в версии 2.9

Аргументы подключения верхнего уровня, такие как username, host, и password, устарели и будут удалены в версии 2.9.

СТАРЫЙ В Ansible < 2.4

- name: example of using top-level options for connection properties
  ios_command:
    commands: show version
    host: "{{ inventory_hostname }}"
    username: cisco
    password: cisco
    authorize: yes
    auth_pass: cisco

Предупреждения об устаревании отражают этот график. Задача выше, запущенная в Ansible 2.5, приведет к:

[DEPRECATION WARNING]: Param 'username' is deprecated. See the module docs for more information. This feature will be removed in version
2.9. Deprecation warnings can be disabled by setting deprecation_warnings=False in ansible.cfg.
[DEPRECATION WARNING]: Param 'password' is deprecated. See the module docs for more information. This feature will be removed in version
2.9. Deprecation warnings can be disabled by setting deprecation_warnings=False in ansible.cfg.
[DEPRECATION WARNING]: Param 'host' is deprecated. See the module docs for more information. This feature will be removed in version 2.9.
Deprecation warnings can be disabled by setting deprecation_warnings=False in ansible.cfg.

Рекомендуется использовать новые типы подключения network_cli и netconf (см. ниже), используя стандартные свойства подключения Ansible и задавая эти свойства в инвентаризации по группам. При обновлении файлов плейбуков и инвентаризации вы можете легко внести изменения в become для повышения привилегий (на платформах, которые поддерживают это). Для получения дополнительной информации см. руководство использование become с модулями сети и документацию по платформам.

Добавление постоянных типов подключения `network_cli` и `netconf`

В Ansible 2.5 введены два постоянных типа подключения верхнего уровня: network_cli и netconf. С connection: local, каждая задача передавала параметры подключения, которые должны были храниться в ваших плейбуках. С network_cli и netconf плейбук передает параметры подключения один раз, поэтому вы можете передать их в командной строке, если хотите. Мы рекомендуем использовать network_cli и netconf по возможности. Обратите внимание, что eAPI и NX-API по-прежнему требуют подключений local с словарями provider. См. документацию по платформам для получения дополнительной информации. Если вам не нужен тип подключения local, обновите свои плейбуки, чтобы использовать network_cli или netconf и задавать переменные подключения с помощью стандартных переменных подключения Ansible:

СТАРЫЙ В Ansible 2.4

---
vars:
    cli:
       host: "{{ inventory_hostname }}"
       username: operator
       password: secret
       transport: cli

tasks:
- nxos_config:
    src: config.j2
    provider: "{{ cli }}"
    username: admin
    password: admin

НОВЫЙ В Ansible 2.5

[nxos:vars]
ansible_connection=network_cli
ansible_network_os=nxos
ansible_user=operator
ansible_password=secret

tasks:
- nxos_config:
    src: config.j2

Использование словаря поставщика с network_cli или netconf приведет к предупреждению.

Разработчики: Утилиты общих модулей перемещены

Начиная с Ansible 2.5, утилиты общих модулей для модулей сети переместились в ansible.module_utils.network.

Платформенно-независимые утилиты находятся в ansible.module_utils.network.common
Платформенно-специфические утилиты находятся в ansible.module_utils.network.{{ platform }}

Если ваш модуль использует утилиты общих модулей, вам необходимо обновить все ссылки. Например, измените: