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

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

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

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

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

Playbook
Устаревшие функции
- Использование тестов Jinja в качестве фильтров
- Именование фактов Ansible
Модули
Плагины
Перенос пользовательских скриптов
Сеть

Playbook

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

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

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

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

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

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 на loop

С выходом 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 в качестве фильтров

Использование предоставляемых 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 в правильный формат. Есть несколько ограничений, и все изменения, сделанные этим скриптом, должны быть проверены на корректность перед выполнением изменённых playbooks. Скрипт можно найти по адресу https://github.com/ansible/ansible/blob/devel/hacking/fix_test_syntax.py.

Именование фактов Ansible

Факты Ansible, которые исторически записывались с именами, такими как ansible_* в основном пространстве имён фактов, были помещены в своё новое пространство имён, ansible_facts.* Например, факт ansible_distribution теперь лучше всего запрашивается через структуру переменных ansible_facts.distribution.

В Ansible.cfg добавлена новая конфигурационная переменная inject_facts_as_vars. Ее значение по умолчанию «True» сохраняет поведение версии 2.4, где переменные фактов устанавливаются в старых ansible_* расположениях (а также записываются в новое пространство имен). Ожидается, что в будущей версии эта переменная будет установлена в значение «False». Когда inject_facts_as_vars установлено в False, вам необходимо обращаться к ansible_facts через новое пространство имен ansible_facts.*.

Модули

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

github_release

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

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

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

nxos_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.4, если вам нужно узнать, как они работали для переноса ваших playbook.

Замечания о устаревании

Следующие модули будут удалены в 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 в рамках функции standardize the behavior of follow:
- Модуль file module изменился с follow=False на follow=True, так как его цель состоит в изменении атрибутов файла, а большинство систем не позволяют применять атрибуты к символьным ссылкам, только к реальным файлам.
- У модуля replace module был удален параметр follow, так как он изначально изменяет содержимое существующего файла, поэтому нет смысла оперировать самим ссылочным объектом.
- У модуля blockinfile module был удален параметр follow, так как он изначально изменяет содержимое существующего файла, поэтому нет смысла оперировать самим ссылочным объектом.
- В Ansible-2.5.3, модуль template module стал более строгим в отношении файла src, требуя правильного кодирования UTF-8. Ранее, не-UTF-8 содержимое в файле шаблона модуля src приводило к повреждённому выходному файлу (не-UTF-8 символы заменялись символом замены Юникода). Теперь в Python2 модуль выдаёт ошибку с сообщением "Файлы шаблонов должны быть закодированы в UTF-8". В Python3 модуль сначала попытается передать не-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.

END_OF_DOCUMENT_MARKER

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

Фильтр

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

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

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

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