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

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

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

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

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

• Playbook

  • Динамические включения и наследование атрибутов
  • Исправленное обращение с ключевыми словами и встроенными переменными
  • Миграция с with_X на loop
  • with_list
  • with_items
  • with_indexed_items
  • with_flattened
  • with_together
  • with_dict
  • with_sequence
  • with_subelements
  • with_nested/with_cartesian
  • with_random_choice

• Устаревшие

  • Jinja-тесты, используемые как фильтры
  • Именование фактов Ansible

• Модули

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

• Плагины

  • Инвентаризация
  • Shell
  • Фильтр
  • Lookup
• Перенос пользовательских скриптов

• Сеть

  • Расширение документации
  • Аргументы подключения верхнего уровня будут удалены в версии 2.9
  • Добавление постоянных типов подключений network_cli и netconf
  • Разработчики: Перемещение общих утилит модулей

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}

Полный список ключевых слов см. в Ключевых словах Playbook.

Миграция с with_X на loop

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

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

with_list

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

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

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

with_items

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

- name: with_items
  ansible.builtin.debug:
    msg: "{{ item }}"
  with_items: "{{ items }}"

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

with_indexed_items

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

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

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

with_flattened

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

- name: with_flattened
  ansible.builtin.debug:
    msg: "{{ item }}"
  with_flattened: "{{ items }}"

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

with_together

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

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

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

Еще один пример со сложными данными

- name: with_together -> loop
  ansible.builtin.debug:
    msg: "{{ item.0 }} - {{ item.1 }} - {{ item.2 }}"
  loop: "{{ data[0]|zip(*data[1:])|list }}"
  vars:
    data:
      - ['a', 'b', 'c']
      - ['d', 'e', 'f']
      - ['g', 'h', 'i']

with_dict

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

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

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

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

with_sequence

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

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

- name: with_sequence -> loop
  ansible.builtin.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
  ansible.builtin.debug:
    msg: "{{ item.0.name }} - {{ item.1 }}"
  with_subelements:
    - "{{ users }}"
    - mysql.hosts

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

with_nested/with_cartesian

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

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

- name: with_nested -> loop
  ansible.builtin.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
  ansible.builtin.debug:
    msg: "{{ item }}"
  with_random_choice: "{{ my_list }}"

- name: with_random_choice -> loop (No loop is needed here)
  ansible.builtin.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 (и ранее) использование встроенного в Ansible jinja-теста, вероятно, выглядело так:

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

Новая конфигурационная переменная inject_facts_as_vars, была добавлена в ansible.cfg. Её значение по умолчанию «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’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.

• Модули 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: https://github.com/ansible/proposals/issues/69

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

Плагины

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

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

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

• Возможность использования плагина кэша для избежания дорогостоящих запросов к 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, по умолчанию используется плагин sh.

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

Filter

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

Lookup

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

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

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

Сеть

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

Мы расширяем документацию по сети. Есть новые материалы и новая стартовая страница 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, каждая задача передавала параметры подключения, которые необходимо было хранить в ваших 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 }}

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

СТАРОЕ В Ansible 2.4

from ansible.module_utils.vyos import get_config, load_config

НОВОЕ В Ansible 2.5

from ansible.module_utils.network.vyos.vyos import get_config, load_config

См. руководство по утилитам модулей Использование и разработка утилит модулей для получения дополнительной информации.