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

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

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

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

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

Плейбук
Устаревшее
- Тесты Jinja, используемые как фильтры
Модули
Плагины
Перенос пользовательских скриптов
Сеть

Плейбук

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

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

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

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

Чтобы получить результат, аналогичный тому, как работало Ansible до версии 2.5, плейбуки должны использовать явное применение атрибута к нужным задачам или использовать блоки для применения атрибута к многим задачам. Другой вариант — использовать статический 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 ключевым словом или переменной при вызове ролей. Если у вас есть плейбуки, которые выглядят так:

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.

Миграция от with_X к циклу

С выпуском Ansible 2.5 рекомендуемый способ выполнения циклов — использование нового ключевого слова loop вместо циклов типа with_X.

Во многих случаях синтаксис loop лучше выражается с помощью фильтров вместо более сложного использования query или lookup.

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

with_list

with_list напрямую заменяется на loop.

- name: with_list
  debug:
    msg: "{{ item }}"
  with_list:
    - one
    - two

- name: with_list -> loop
  debug:
    msg: "{{ item }}"
  loop:
    - one
    - two

with_items

with_items заменяется на loop и фильтр flatten.

- name: with_items
  debug:
    msg: "{{ item }}"
  with_items: "{{ items }}"

- name: with_items -> loop
  debug:
    msg: "{{ item }}"
  loop: "{{ items|flatten(levels=1) }}"

with_indexed_items

with_indexed_items заменяется на loop, фильтр flatten и loop_control.index_var.

- name: with_indexed_items
  debug:
    msg: "{{ item.0 }} - {{ item.1 }}"
  with_indexed_items: "{{ items }}"

- name: with_indexed_items -> loop
  debug:
    msg: "{{ index }} - {{ item }}"
  loop: "{{ items|flatten(levels=1) }}"
  loop_control:
    index_var: index

with_flattened

with_flattened заменяется на loop и фильтр flatten.

- name: with_flattened
  debug:
    msg: "{{ item }}"
  with_flattened: "{{ items }}"

- name: with_flattened -> loop
  debug:
    msg: "{{ item }}"
  loop: "{{ items|flatten }}"

with_together

with_together заменяется на loop и фильтр zip.

- name: with_together
  debug:
    msg: "{{ item.0 }} - {{ item.1 }}"
  with_together:
    - "{{ list_one }}"
    - "{{ list_two }}"

- name: with_together -> loop
  debug:
    msg: "{{ item.0 }} - {{ item.1 }}"
  loop: "{{ list_one|zip(list_two)|list }}"

with_dict

with_dict можно заменить на loop и либо фильтр dictsort, либо dict2items.

- name: with_dict
  debug:
    msg: "{{ item.key }} - {{ item.value }}"
  with_dict: "{{ dictionary }}"

- name: with_dict -> loop (option 1)
  debug:
    msg: "{{ item.key }} - {{ item.value }}"
  loop: "{{ dictionary|dict2items }}"

- name: with_dict -> loop (option 2)
  debug:
    msg: "{{ item.0 }} - {{ item.1 }}"
  loop: "{{ dictionary|dictsort }}"

with_sequence

with_sequence заменяется на loop и функцию range, и, возможно, фильтр format.

- name: with_sequence
  debug:
    msg: "{{ item }}"
  with_sequence: start=0 end=4 stride=2 format=testuser%02x

- name: with_sequence -> loop
  debug:
    msg: "{{ 'testuser%02x' | format(item) }}"
  # range is exclusive of the end point
  loop: "{{ range(0, 4 + 1, 2)|list }}"

with_subelements

with_subelements заменяется на loop и фильтр subelements.

- name: with_subelements
  debug:
    msg: "{{ item.0.name }} - {{ item.1 }}"
  with_subelements:
    - "{{ users }}"
    - mysql.hosts

- name: with_subelements -> loop
  debug:
    msg: "{{ item.0.name }} - {{ item.1 }}"
  loop: "{{ users|subelements('mysql.hosts') }}"

with_nested/with_cartesian

with_nested и with_cartesian заменяются на цикл и фильтр product.

- name: with_nested
  debug:
    msg: "{{ item.0 }} - {{ item.1 }}"
  with_nested:
    - "{{ list_one }}"
    - "{{ list_two }}"

- name: with_nested -> loop
  debug:
    msg: "{{ item.0 }} - {{ item.1 }}"
  loop: "{{ list_one|product(list_two)|list }}"

with_random_choice

with_random_choice заменяется на простое использование фильтра random, без необходимости loop.

- name: with_random_choice
  debug:
    msg: "{{ item }}"
  with_random_choice: "{{ my_list }}"

- name: with_random_choice -> loop (No loop is needed here)
  debug:
    msg: "{{ my_list|random }}"
  tags: random

Устаревшее

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

Использование тестов Jinja, предоставляемых Ansible, как фильтры, будет удалено в 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 в правильный формат. Есть несколько ограничений, задокументированных, и все изменения, внесенные этим скриптом, должны быть оценены на корректность перед выполнением измененных плейбуков. Скрипт можно найти по адресу 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 используйте опцию system_mtu nxos_system или 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 соответственно.

Модули aos_* Apstra устарели, так как они не работают с 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.
Несколько модулей, которые могли работать с символическими ссылками, изменили значение по умолчанию своего параметра follow в рамках функции по стандартизации поведения follow:
- Модуль file module изменил значение по умолчанию параметра follow=False на follow=True , так как его цель - изменить атрибуты файла, а большинство систем не позволяют применять атрибуты к символическим ссылкам, только к реальным файлам.
- У параметра follow модуля replace module была удалена, так как он изначально изменяет содержимое существующего файла, поэтому нет смысла выполнять операцию над самой ссылкой.
- У параметра follow модуля blockinfile module была удалена, так как он изначально изменяет содержимое существующего файла, поэтому нет смысла выполнять операцию над самой ссылкой.
- В Ansible-2.5.3 модуль template module стал более строгим в отношении правильности кодировки UTF-8 файла src. Ранее содержимое файлов шаблонов, не закодированных в UTF-8, приводило к повреждению выходного файла (символы, не закодированные в UTF-8, заменялись универсальным символом замены). Теперь в Python 2 модуль будет выводить ошибку с сообщением «Файлы исходного кода шаблона должны быть закодированы в UTF-8». В Python 3 модуль сначала попытается пройти символы, не закодированные в UTF-8, непосредственно и завершится ошибкой, если это не удастся.

Плагины

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

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

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

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

Shell

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

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

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

Полный список см. в используемом вами плагине shell, плагин shell по умолчанию — 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 и задавая эти свойства в инвентаре по группам. При обновлении ваших файлов playbook и инвентаря вы можете легко внести изменение в become для повышения привилегий (на платформах, которые это поддерживают). Дополнительную информацию см. в руководстве использования become с модулями сети и документации платформы.

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

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

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